cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: ideas?
Date Thu, 27 Mar 2003 14:56:55 GMT

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


Mime
View raw message