Hi Bertrand, > Sorry about that. I guess some of us are in a more or less burnout > state about the docs (I am).
Hmm, it's more difficult to write good documentation than write good code. > There have been many discussions about how to improve the docs, many > real good ideas flying around (moving everything to the wiki, > generating reference docs from code, generating table of > contents from > keywords in docs, etc), but until now not much has been done in terms > of restructuring / making the docs more accessible. Many talks, not > much action (I'm as guilty as anyone, not pointing fingers). Well, in my opinion a ToC is about the only thing that can be "generated" when talking about documentation. All the rest is more craftmanship from a writers POV than from a developers POV. Sure, javadoc in the code surely helps, but it's often too limited. > So yes, your TOC initiative is very welcome! Thanks. > A while ago I started writing "documentation tracks" [1]. Would a > merging of the two concepts (your TOC and these tracks) be useful? I > think it's about the same idea: provide a roadmap into the docs. Yes I noticed on the wiki, my idea exactly to merge them, although my plans with the ToC are more "grand". As explained in another message, my goal is to get to an ebook kind of documentation. At first, I'll include the pages in the ToC (or you can do that yourself if you feel like), in later steps I suppose we have to integrate them into the documentation. The idea is great though. Bye, Helma
