> > - pick a tool, any tool that meets the criteria I mentioned > above and > > start a new set of documentation there. I suggest Daisy. > > What you should be concerned about is managing new and existing > content. This includes some process for accepting vetting, editing/ > correcting and publishing.
In short a CMS type of tool > Why require a particular tool? Is everyone who contributes code to > Cocoon required to use Eclipse? Since documentation is best gathered in a CMS, because there will likely (hopefully) be more than one person working on it, this inevitably means that everyone should use THAT CMS to avoid scattering documentation all over the place (wiki, website, mailing list, blogs, own websites etc). > What if the new document is far superior to the existing in terms of Hurray for that. But if you've come up with something that replaces information in other places, do note that in both "origin" and "destination" to avoid others duplicating the effort. > content and clarity? Who decides this? Do we leave this decision to > the author? Frankly if I'm going to write some documentation, I'm > going to do it because I'm unhappy with what exists and I am likely > to start from scratch or just completely rewrite what exists. Great! Go ahead. If you feel comfortable enough to write something about any aspect of Cocoon, please do. The only thing I ask from reviewers (aka Cocoon committers) is that they read your document and compare what you write to the actual working of Cocoon to see if there are discrepancies that might lead to false conclusions/understanding from other users. > This is an essential step in producing good documentation. It is also > a very time consuming one. Experts are very useful when it comes to > verifying the broad pictures and approaches but to often their > knowledge of the field makes it easy for them to understand the > intention of the author when a newbie will be completely lost. OTOH If you write down that CForms has a state 'readonly' when in fact it's 'disabled' that's something Sylvain e.g. will probably notice immediately while it takes trial and error of 'ordinary' users to figure out. > Unfortunately this leads to pretty much the same state we > have now, a > lose collection of documents some easy to locate and some buried > deep. Someone needs to manage the documentation. Someone needs to > organize it. While this can be a community effort ultimately > decisions need to made as to where documentation is to be > located and > organized and this needs to be done in a consistent manner. True, but even the multiple attempts to come up with a general TOC have failed so what now? Putting all documentation in one place (at least the 'user guide' type which is most needed anyway), following a general structure/TOC is still better than the current state. > The issues are different, but of course rules are needed. With code, > test can be run to verify correctness. Bugs pop up as others work on > different parts of the code. With documentation decisions need to > made by people as to its value, its understandability and where it > fits in the grand scheme of things. Someone needs to go through it > and insert the appropriate hyperlinks. Random documents no > matter how > informative will not make Cocoon any easier. Its as much about > organization and ease of use from a users point of view as it is > about content and currency. Ok. Let's sit down then and dream up a general TOC by studying the attempts done earlier. Bye, Helma
