Date: 2005-01-08T11:14:44 Editor: MarkLundquist Wiki: Cocoon Wiki Page: ExtremeDocumentationOverhaul URL: http://wiki.apache.org/cocoon/ExtremeDocumentationOverhaul
no comment Change Log: ------------------------------------------------------------------------------ @@ -127,3 +127,52 @@ == <to be continued> == + +MarkLundquist comments: + +__[1]__ (I'm listing this comment first, not because it is the most important -- it isn't -- but because it's the most general). Just to clarify (and maybe the title of this page doesn't do it justice), the proposal here isn't limited in scope to just the Cocoon documentation ''per se'', although it certainly does include that, but really it's about a whole new official Cocoon site, is that correct? See also comment [5] below... + +__[2]__ +1 on all the desiderata listed under ''"General Principles"'', and also your proposed approach... + +...with the notable exception of ''Eliminate the wiki''. + +The Cocoon project needs a Wiki and probably always will. The Wiki is a good thing! Its use as front-line documentation is arguably bad, but it also arguably represents a current best effort (it's better than no docs at all!). Your proposal w.r.t. the wiki approaches it from the wrong end. We don't have poor real docs because we have docs in the wiki, we have docs in the wiki because we have poor real docs. The idea, IIRC, was to use the wiki as a staging area for new doc material. That seems like a sound approach, so let's just (a) make sure that the new docs do what we want them to do (this relates to all the organizational and content principles you've outlined, and (b) finish the job, i.e. makes sure the good stuff gets promoted from the wiki to the real docs. It's possible that one reason that proto-docs have languished in the wiki is because of dissatisfaction/uncertainty about the lapsed state of the official docs, e.g. "this is good stuff, but where should it go?", or "lets wait until the doc overhaul to merge this in". + +Striking elimination of the wiki from your proposal will correct its scope and make it more acceptable. + +Once the real docs are up to snuff, the original wiki pages should be replaced with notices that say "this page has been superseded by <this> on the Cocoon site. Please go there for the most current information for Cocoon 2.1". We do that rather than deleting them, so that people who have wiki pages bookmarked have somewhere to go. Insiders doing archaeology on the docs can always look at historical versions of the wiki pages. + +__[3]__ It seems to me that your example document users A, B & C are probably in fact exactly the most common profiles, and we should consider them to be the actual target profiles for this effort. + +__[4]__ W.r.t. the "ruthless deletion" (+1!) + +I think this should start with everything that doesn't represent current best practices. + +Whatever is deprecated or clearly on the path for deprecation should be annexed off so that it is clear that it no longer represents current thinking. The last time Cocoon docs got the level of effort they deserve was for "old Cocoon", which means that Actions, XSP & Logicsheets, and to a degree the idea of custom sitemap components, all still figure prominently. It may be that one reason that stuff hasn't been touched is the feeling that "new Cocoon" is in certain respects not yet "ready for prime time", or at least that its documentation isn't. But that is a bad think. The best that can happen with such an approach is that users eventually figure it out anyway, but only after wasting a bunch of time trying to learn obsolete concepts. It's time to be honest in the docs. Yank everything that's only relevant to "old Cocoon", and if there's nothing yet to replace it, we should just be honest and say something along the lines of + + * Cocoon has a really cool system for this, which we call 'X'. Unfortunately we haven't managed to get some documentation written for it yet, so in the meaintime you can check out these resources: + * [whatever samples] + * [wiki articles] + * [list archive references] + +Or, + + * There isn't a great way to do X right now that doesn't require writing some Java code. We're trying to figure out a better way; in the meantime, if you have some Java skills, here's how you do it: <link to wiki page or whatever>. + +The current docs give the impression of Cocoon being more complete and better documented that it really is, and maybe we don't want to lose that "impression"... but we do users a disservice by hanging onto the obsolete stuff. We have a "double-hump" technology situation here and we're still a bit in the "gap" betwen old Cocoon and new Cocoon, but I think we should still be as accurate and honest as possible. + +__[5]__ Look and Feel + +This comment is probably most relevant to your "User A" profile, the corporate manager. + +Visual design communicates a message. For the current Cocoon site, that message is, "Made for geeks, by geeks". It has that tab-y, Forrest look. The Apache branding is very strong. What's wrong with being strongly identified w/ Apache? Absolutely nothing. So what's wrong w/ the Apache branding? Just that it ''happens'' to be kind of sucky-looking, that's all! + +Compare cocoon.apache.org w/: + * orixo.com + * wyona.com + * orbeon.com + +So assuming we had a better design in mind, what are the tactical details for implementing it? + +''[hmmm... I have some thoughts but I have to close this post out for now. To Be Continued...!]'' +----
