cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Brian Topping" <topp...@digidemic.com>
Subject RE: Wiki documentation system
Date Fri, 07 Jun 2002 14:40:04 GMT
> -----Original Message-----
> From: Andrew C. Oliver [mailto:acoliver@apache.org]
> Subject: Re: Wiki documentation system
> 
> +1 -- But while we're all talking about all the cool tools we could 
> develop/use to document...let us not forget the actual
> process of clicking keys and generating textual content...

My perspective for proposing all of this was that I am only a few months into using C2.  I'm
not a bad hack either.  So when something is hard for me to accomplish, it strikes me that
there is probably an opportunity for better documentation.  But if the documentation process
(context diffs contributed as patches to bugzilla) is more difficult than the change itself
(maybe a sentence or two in some cases), I am less inclined to make a contribution since I
also need to get work done toward my own goals.

I think your point is that developers need to document their work and I think it's relevant...
BUT!  I personally don't think that "developer A" that has lived with their own code for the
weeks that it takes to develop it have a very good *user* perspective any more, and it makes
it hard to write good docs.  "Developer B" that is picking up the technologies that Dev A
wrote last week is a better candidate to write the docs -- they are taking a fresh look at
the results and what it takes to install it and get it running.  

So we ought to consider a documenting each other's work.

These "install and get running" docs get new users hooked on the technology, and getting them
hooked like that is really the key to seeding a new technology since some of those new users
are going to realize how bad the rest of the documentation is and start in on that eventually.
 

IMHO there is coming of age... people that are new to the project *should* write docs first
because they have experience with where they got caught up.  It's valuable experience that
shouldn't be thrown away, but valuable contribution nonetheless.

Me?  I'm just getting ready to write some docs!!  :)

-b

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message