Diana Shannon wrote: > --------- > 1. Assessing needs <snip/> > Note the meaning of following symbols: > + existing documentation meets this need > - existing documentation partially meets this need > o no documentation currently meets this need > > Evaluating C2 (new users, managers, administrators, press) > - conceptual, big-picture pieces > - news > - features > o requirements > o (links to) third party reviews, press > o success stories > o comparison to other technologies/approaches > o development roadmap
o Business cases Various one-page exec summaries, that people can utilise to convince their powers-that-be. > Learning to use C2 (introductory/intermediate/advanced users) > - conceptual, big-picture pieces > - FAQs > - tutorials (multiple levels) > - guides to additional components > o manual > o learner's roadmaps > o glossary of terms > o (links to) external resources/aids > > Developing with C2 (introductory/intermediate/advanced users) > + API reference > + Bug Database > - FAQs > - how-tos (download, build, install, configure, test, debug, extend, > etc.) > - sitemap components reference guide > - configuration reference guide > - samples/snippets/cookbook > - hosting information > o best practices > o (links to) external resources/aids > > Contributing to C2 (community donations of code, documentation, > resources, etc.) > + Bug Database > + Code Respository > + to do (code) > + instructions (for developers) - instructions (for developers) ... this area needs more work. As a new committer, i found a lot of troubles getting started. It seemed that i was trying to figure it out from scratch, e.g. to whom does one send email about troubles with ssh/cvs (i.e. this is not public info). I did gain clues by browsing doco from other projects. > o how-tos > o FAQs > o instructions (for all other types of contributions) > o source code style conventions > > --------- > 2. Accessibility > Considering the documenation that already exists, how can we make it > more readily accessible? In other words, how can we reduce the amount of > time and effort required to locate and apply the necessary information? > How do we avoid information fragmentation? Please add/delete/edit as you > see fit. > <snip reason="agree with all" /> Problem: Hard to know which documents have been updated between releases. Solution: Perhaps the generated Table-Of-Contents doclist could be enhanced to show the last-modified date. Problem: There is generally only one path to get to a certain document Solution: Need more cross-references and better use of section identifiers so that one document can refer directly to the relevant section of another doc. Sometimes "content overlap" is necessary, while sometimes it is better to refer to a section of some overview. > ----------- > 3. What do you consider to be reasonable short- and long-term goals of > this effort? What should be the priorities? Short-term: *) Develop a set of planning documents (see below). *) Improve doco which shows "how to contribute". *) Develop a solid structure for FAQs (existing FAQ needs to be split into various topic-based ones). *) Develop a solid structure for HOWTOs. Should this follow LinuxDoc or should it be based on our document.dtd ? *) Concentrate on a couple of shining example HOWTOs to get the ball rolling, which can serve as guidelines. It would be a mistake to start off a mass of HOWTO documents with minimal content and inconsistent layout. Long-term: *) Lead by example and encouragement. *) Develop facilities to validate XML during build docs. Trap any errors at the contributer's end. This eases the task for a committer to apply a patch. At one stage, we did have validation working, but it had to be switched off for some obscure reason. > ----------- > 4. How can we make the best use of available resources? How can we > leverage untapped resources within the Cocoon community? Encourage the user community to "own" the documentation along with the dev community. This is another of the big opensource misconceptions. The general user thinks that there is a separate "team of developers" that produce the software/doco. > ----------- > 5. How do we focus our efforts to complement -- not compete with -- > third-party book and training efforts? ...<snip/> Produce such brilliant on-line doco that it removes the need for anyone to replicate it. In that way they can build upon the base and concentrate their efforts on higher things. > ----------- > 6. What documentation projects/examples do you admire? Any URLs or > specific references will be greatly appreciated. FAQ-O-Matic. SUNs original "Java Tutorial" Trails. LinuxDoc. > ----------- > 7. What's currently difficult about contributing/authoring documentation > for C2 right now? How can we improve that process? I wonder if the general user realises the vision of opensource, and that the onus is on them to fix any lack that they perceive. Perhaps they do not realise how easy it is to participate. I think that a lot of people are afraid because they do not understand. The section "CVS Usage Precis" recently added to contrib.xml should help to encourage them to send diffs rather than complaints. > ----------- > 8. How can we make it easier/more inviting for people to participate in > the document development process? What kinds of architectural mechanisms > can we implement to support document development/refinement, given the > current hosting environment of Cocoon's web site? *) Maintain a set of planning documents. Perhaps we could keep a set of evolving documents in CVS. A while back we did set up an area for "Planning". It has only been used a little, but the structure is there ... src/documentation/plan/ We have often had such planning discussions before, but content tends to remain hidden in the email archives. *) The actual Cocoon website doco needs to be updated far more regularly. At the moment, it is only updated when a software release happens, which is not often enough. A quicker turnaround on document edits, would encourage more participation. Perhaps a separate doc-changes.xml *) Keep doco development work on cocoon-dev list (we cannot let developers get out of of this loop) *) Encourage better use of email subject lines, and one topic per thread. *) Send planning summaries to cocoon-dev list regularly. *) Send progress summaries to both lists. Perhaps an automated summary can be generated each week to show the documentation progress. --David Crossley --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
