Hi David, > > section. My ultimate goal is an ebook kind of documentation. > > Great idea. This is then orthogonal to the total > restructuring of the xdocs, which was shelved until 2.2 > because it would otherwise break our URL space.
AHA. That explains the "complete radio silence" when it comes to updating the documentation. :-) > I would certainly like to see this ToC cater for the > anticipated "Reference documentation" (cannot find old dev@ > or old docs@ discussion yet). What exactly do you mean by "reference documentation"? To me it's a mixture of JavaDocs + extra explanation + textual examples and maybe even a live working example in the "samples" section. > > Part of the documentation in my view is also a section on > "Cocoon info > > in the rest of the world", although this might very well be a wiki > > page. > > Well i think that we should start that now, then keep > this page clean. Ok. > One thing that we had discussed about Cocoon core xdocs > documentation was that it should not appear to sanctify any > external documentation, because there is some stuff out there > that we may not be happy with and where do we draw the line. Hmm, maybe it's simply my understanding of English, but I don't really understand what you mean here. Do you mean that "no" external reference should be included or "all"? I was thinking along this line: - references to external URLs that explain "add-ins" for Cocoon, e.g. the flowscript debugger, the Sunbow plugins for Eclipse etc. - references to blog entries which explain some otherwise hard to find info. - references to mail archives. - references to articles on Cocoon (e.g. the TSS article lately) - anything else I've forgotten The latter 2 are stuff for the Wiki page. For the first 3 I'm thinking of getting in touch with the original authors and ask permission to include/rewrite the information and include it in the Cocoon xdoc itself. When components are involved, links are included to the authors pages for more info and downloads. This would be my option, because I've experienced myself numerous times where I "searched myself colorblind" to find information on a certain topic, only to stumble across it in a totally unrelated description or after much mailing back and forth on the mailing list. For me a good product has 2 main aspects: 1. It works more or less out of the box and works as expected, 2. If not, there is a good manual where I can look (most) things up. From my POV Cocoon has (1), but lacks (2) in the sens that the information is probably "somewhere", but it cannot be found easily. > Also we do not want to get into URL management and dead > links. So yes, a separate Wiki page sounds better. My idea. > There is one aspect that i am still not clear about. Do you > envisage that this ToC itself would become an xdoc? I hope Yes. Every book needs a ToC, an ebook even more so. In fact, it would also need an index. (sigh, even more work :-) ). > so. If so, then that is why i would like it to be free from > references to external cocoon-related stuff. Ok, I'll start a new Wiki page. Bye, Helma
