ideas?

[Tony Collen <tc...@neuagency.com>]

Diana/Everybody:  Any thoughts on my proposed docs reorg?
(wiki.cocoondev.org/Wiki.jsp?page=DocsReorgProposal )


Any feedback would be nice.... I think there's a ton of stuff in the
actual docs that I'm missing that could probably be integrated into the
outline.


Tony

Re: ideas?

[Bertrand Delacretaz <bd...@codeconsult.ch>]

Le Mercredi, 26 mars 2003, à 19:11 Europe/Zurich, Tony Collen a écrit :

> Diana/Everybody:  Any thoughts on my proposed docs reorg?
> (wiki.cocoondev.org/Wiki.jsp?page=DocsReorgProposal )...

Hi Tony,

I like your plan - here are some ideas/comments, but overall I'm ok 
with it.

"Getting started":
I'd keep this minimal by not putting reference info about the build 
here. Just the minimum to get Cocoon up and running, with links to 
reference info about the build (if needed, but it might be better to 
put the reference info into install.txt directly).

"Configuring Cocoon":
In the same way I think this belongs to a "Reference" section which 
would contain "Component Reference" and other reference info.

"How-Tos/Tutorials":
I'd put this as the second section (second tab on the web site)

"Debugging":
I don't think this deserves a separate section, could go into How-Tos 
maybe? or Reference?


I haven't checked if your plan includes all the current documentation 
but I wouldn't scrap any of the existing docs yet, maybe put them in a 
"legacy docs" section or something until the new docs plan stabilizes.

Thanks for your work!
-Bertrand

Re: ideas?

[Diana Shannon <sh...@apache.org>]

On Wednesday, March 26, 2003, at 01:11  PM, Tony Collen wrote:

> Diana/Everybody:  Any thoughts on my proposed docs reorg?
> (wiki.cocoondev.org/Wiki.jsp?page=DocsReorgProposal )

Thanks for hollering and for getting the ball rolling!

> Any feedback would be nice.... I think there's a ton of stuff in the
> actual docs that I'm missing that could probably be integrated into the
> outline.

The problem I have with this kind of approach is that it "feels" 
top-down. Please understand that I'm not saying it shouldn't be done. 
However, one person's preferred TOC will be different than another 
person's, based on context of use, skill/ability levels, project needs. 
I much prefer a rather minimal TOC with links to multiple  
"documentation tracks" as proposed and started by Bertrand on our Wiki.
   http://wiki.cocoondev.org/Wiki.jsp?page=DocumentationTracksProject

Here's why.

1. No matter how brilliant a TOC may be, if we lack the content to fill, 
users will be frustrated when they encounter those pages that say -- 
CONTENT COMING/MISSING/NEEDED. Documentation tracks, based on links to 
more focused, granular, content-- available **now** (not at some 
hoped-for future point) -- seems more useful to me.

2. Creating documentation tracks will inform a larger TOC "trail" 
revision down the road. Therefore, why don't we split this massive TOC 
into sections and think about various documentation tracks within each? 
Perhaps we could post ideas to the existing Wiki page on tracks.

3. Volunteer authors typically haven't yet come forward with the 
request -- "I want to write docs. Where do I fill in the blanks?" No, 
usually they have a specific doc they want to write, whether or not 
there's an existing "blank" for it somewhere in our documentation set.

4. I still see a majority of "new" content coming in via Wiki. 
Developing documentation trails based on wiki links seems to me to be 
more grassroots approach to this reorganization issue. If we need to 
move existing docs on to wiki, and/or make them more granular, then I'm 
more than +1 and will volunteer to do this.

Don't get me wrong. I still think what you are doing is both useful and 
timely. However, can we think of it more broadly, not specifically 
related to how a single, specific user doc might be organized? For 
example, we really need a systematic approach to how How-Tos and FAQs 
are indexed, based on some thoughtful organization of content topics. We 
could apply this approach to those areas as well.

Thanks Tony and Bertrand.

Diana