Date: 2005-01-08T21:41:05 Editor: DavidLeangen Wiki: Cocoon Wiki Page: ExtremeDocumentationOverhaul URL: http://wiki.apache.org/cocoon/ExtremeDocumentationOverhaul
no comment Change Log: ------------------------------------------------------------------------------ @@ -28,6 +28,7 @@ The contributors to this little "project" are: * DavidLeangen + * MarkLundquist * <your name here> ---- @@ -127,52 +128,134 @@ == <to be continued> == +== Discussion Between Mark and David == + +=== General === + +MarkLundquist comments: + + (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... + +DavidLeangen replies: + + Ok, good point! How about we change the title of the page to something like design_of_new_official_website (name intentionally written this was so as not to inadvertently create a new wiki page)? + + Indeed, the proposal here goes beyond just the documentation. It is intended to also help with the communications aspect of the project. I feel that from a marketing perspective, much work needs to be done. The long-term success of Cocoon will, IMHO, also depend on its wide-spread adoption in industry, and not just on the core community. + + I believe that such an approach is not necessary with, say, Apache Server. Why? Because it is not a product aimed at the "general population", so to speak. A sysadmin will install it once and, well, that's pretty much it. Cocoon is very different. In an enterprise, several people will be involved in working with Cocoon on a daily basis. The way the company evaluates and uses the product is much different. So, just because things worked well at Apache until now with other projects (such as HTTP Server), that does not mean that the same approach will work for Cocoon. + +=== Elimination of Wiki === + +MarkLundquist comments: + + +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. + +DavidLeangen replies: + + I generally agree with your comment. I had never thought about in this way before and I appreciate your insight. + + How about a slightly different approach, then? First, let's agree on the goals: + + * we want to use the wiki as a kind of "incubation" area for new information + * useful information should be incorporated into the main website + * "successful" pages will be replaced by a reference to the new page in the website + * "unsuccessful" wiki pages should be kept for historial purposes + + I agree with all of these goals. (Except I am worried that the reference used for a "successful" page will soon be outdated--and therefore quite useless.) + + I further propose: + + * the wiki should ''not'' be used as a main source of information + * the wiki should only be used as a source of information for those really pushing the boundaries of what Cocoon can do and is intended for + * the wiki should not be "endorsed" as a source of information + * information on the wiki should not be supported (if it is, then it belongs on the official site!) + * we need a mechanism to "outdate" old wiki pages + + So, with these two sets of goals in mind, one approach we could use is, for each new release of Cocoon, ''all'' wiki pages get archived. Above in the proposal, I propose deleting a page after 6 months, but this conflicts with the goals we just set here. By archiving all files after a new release, we would ensure that: + + * pages are no longer out-of-date (authors or interested persons will move a valid page back to the current wiki area if the information is still valid) + * the wiki remains clean and useable for its intended purpose + * the wiki does not become the main source for consulting Cocoon info + * we keep information for historical purposes + + I think that we (and many others) agree that, while the wiki is useful, it has become a problem. I believe that we need to take a radical approach to solving the problem. Perhaps eliminating it all together goes too far, I agree. However, I think that we should nonetheless include ''some'' type of solution. + + +=== User Profiles === 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... + 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. + + +=== Deprecation of Documents === + +MarkLundquist comments: -__[2]__ +1 on all the desiderata listed under ''"General Principles"'', and also your proposed approach... + W.r.t. the "ruthless deletion" (+1!) -...with the notable exception of ''Eliminate the wiki''. + I think this should start with everything that doesn't represent current best practices. -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". + 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 -Striking elimination of the wiki from your proposal will correct its scope and make it more acceptable. + * 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] -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. + Or, -__[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. + * 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>. -__[4]__ W.r.t. the "ruthless deletion" (+1!) + 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. -I think this should start with everything that doesn't represent current best practices. +DavidLeangen replies: -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 + That makes sense. The product is always in a state of evolution. - * 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] + I think that we need to separate what is "cutting edge" from what is "standard cocoon". If we consider a classic bell curve for the evolution of a typical product, the vast majority of our potential users do not want to live on the cutting edge. They want something that is proven, stable, and reliable. -Or, + Another point that bothers me is that there are so many ways to do one thing. I have brought up this issue before and quickly learned that several people believe this to actually be an advantage of Cocoon. It is not my place to say what is best, but I do strongly believe that for the user profiles we are targeting, by far the best approach is to have a "standard" set of best practices. - * 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>. + Ok, the above topics diverge somewhat from your comment, so to reply directly: if the feature exists, then it needs to be documented on the webpage. Period. Now, the problem is: who will do this? Nobody wants to do documentation... so how do we pull this off? -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. +=== Look and Feel === -__[5]__ Look and Feel +MarkLundquist comments: + + 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? + +DavidLeangen replies: + + It's true the the Apache brand is something worth building on. For the rest see my comment above concerning the nature of Cocoon vs. other successful Apache projects. + +=== Random Thoughts === + +MarkLundquist comments: -This comment is probably most relevant to your "User A" profile, the corporate manager. + ''[hmmm... I have some thoughts but I have to close this post out for now. To Be Continued...!]'' -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! +DavidLeangen replies: -Compare cocoon.apache.org w/: - * orixo.com - * wyona.com - * orbeon.com + Ok, I look forward to hearing about them! :-) -So assuming we had a better design in mind, what are the tactical details for implementing it? + Thanks for taking the time to comment on all this stuff. -''[hmmm... I have some thoughts but I have to close this post out for now. To Be Continued...!]'' ----
