cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [Cocoon Wiki] Updated: ExtremeDocumentationOverhaul
Date Sat, 08 Jan 2005 19:14:44 GMT
   Date: 2005-01-08T11:14:44
   Editor: MarkLundquist
   Wiki: Cocoon Wiki
   Page: 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
+...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
+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]
+ * 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 w/:
+ *
+ *
+ *
+So assuming we had a better design in mind, what are the tactical details for implementing
+''[hmmm... I have some thoughts but I have to close this post out for now.  To Be Continued...!]''

View raw message