On Monday, November 18, 2002, at 03:54 AM, Bertrand Delacretaz wrote:
Hi cocoon-docs,
Following up on the recent "documentation format" thread, here's a proposal
for a one-page documentation plan that we might publish on the website.
I think publishing a community-revised version of this plan on the website
might help would-be authors in deciding how to help.
Good idea. I agree this would help authors.
The idea is to split the docs projet into five areas (Concepts, Tutorials,
Reference, Navigation, Wiki).
Hmm... You forgot
- FAQs
- Snippets
- topics (not implemented yet)
- dictionary (a wikiland project?)
- user guides (multiple) IMHO reference guide != user guide.
- recipes (as suggested by Stefano earlier on cocoon-dev, not implemented yet -- need How-To on this)
- success stories (not implemented yet -- need How-To on this)
I wouldn't combine Tutorials and How-Tos a single doc type. Sometimes you just need a basic how-to to accomplish something. Simple steps for those of us with *no* time to learn something new each and every time we happen to do something new. It would be nice to master this or that concept every time we do something different, but the reality remains that we don't have enough time -- at least initially. Tutorials should teach, as well as show how to do something. Tutorials contain how-to information but they **also** contain conceptual information. How-Tos are just the facts, nothing more. Tutorials help you apply knowledge to a range of problems, not just the problem at hand. I'm sorry I haven't made this clearer yet (e.g. no How-To on tutorials). I realize others may blur this distinction, but I'd rather not.
Also, I'm not sure I like a separate category for Concept docs. They tend to be weak unless kept very general. They also require a high level of knowledge to write well. Better, use concepts within other doc types, followed by examples and implementation content. One of the major problems with our current user guide is that we have separate pages for concepts and component descriptions/details. It makes it **very** difficult to navigate efficiently while learning.
<snip />
Navigation layer
--------------------
A navigation layer, decoupled from the physical docs structure ,is needed to
make the docs easy to find and to implement permanent URLs for reference docs
(I think Forrest/Libre will help here?).
I'd like the WikiTextGenerator manpage, for example, to be found under
docs/reference/generators/WikiTextGenerator.html, irrelevant of where the
docs come from (including if they come from a Block later?).
The top-level navigation uses the same categories: Concepts, Tutorials, Reference and Wiki.
I don't understand how this is a separate area. Do you mean road map/learning trail docs?
Wiki
-----
The Cocoon DocoWiki acts as a kind of scratchpad for draft documents or for
annotations to existing docs.
Note that having permanent URLs for docs might allow using the Wiki for annotations, by defining a mapping from docs URLs (as above for WikiTextGenerator) to Wiki pages that contain notes .(.wiki.jsp?page=NotesOnReferenceGeneratorsWikiTextGenerator). Links to the annotations pages could then be generated in the docs.
Yes, I think this should be implemented asap. Can we have a consistent URI pattern for mapping between existing docs and their Wiki-based notes pages so it's easy to generate the links automatically? Since I'm not familiar enough with JSPWiki, is it possible to generate these note pages offline/on the server (i.e. not through the browser)-- otherwise, it's a lot of manual work for someone.
<snip />
[1]
For manpages, I like separate XML files better, using naming conventions, for
example
src/components/MyComponent-manpage.xml describes src/components/MyComponent.java
When programming, I wouldn't want my NiceAndSimpleComponent.java file to contain too many javadoc tags and documentation text.
+1
I've done a lot of work and thinking in this area. I'll be **happy** to supplement your proposed text but I don't have time at the moment. Need to finish my Forrest transition-related work.
Thanks for the good start here.
Diana
