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.
The idea is to split the docs projet into five areas (Concepts, Tutorials,
Reference, Navigation, Wiki). I know this has been discussed before, but I
think the recent discussions about manpages and javadoc tags bring new light
to this issue, and I don't think we have a precise doc plan yet.
Maybe we should publish this on the website in table form, including a
summary of tasks in each area? I can prepare an xdocs version of this once/if
we agree on the content.
- o -
Here's the plan (including a number of questions marks):
Concepts docs
-------------------
Describe Cocoon at a high level: purpose, architecture, component types,
usage examples, strengths and weaknesses, similar systems.
Also point the reader to books and articles.
Written by doc authors who are not necessarily developers.
Stored separately from the source code (different directories in the current
CVS, maybe separate CVS later).
Tutorial docs
----------------
Tutorials and How-Tos, used by someone who, based on the Concepts, decides to
try or use Cocoon.
Written by doc authors who are not necessarily developers, maybe users that
know about some component without necessarily having the big picture required
to write on Concepts.
Each tutorial must include links to all components used (allows a map of
docs/component dependencies to be built?)
Stored in the same way as Concepts, separately from the code.
Reference docs
--------------------
Detailed information on every component, in unix manpage style: one page for
each component, always with the same document sections, including a "see
also" section.
Must be written by developers (at least in draft form) when components are
created. Might be revised by doc authors later on.
Might be generated from javadoc tags, or using separate XML files stored in
the component's source code directories [1].
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.
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.
Appendix: Documentation Format
-------------------------------------------
Base format is xdocs, some documents being converted to xdocs from other
formats (howto DTD, javadoc tags, ?) on the fly using Forrest.
- o -
That's only a first shot at this plan, of course ideas/flames/contributions
are welcome.
I leave for the Ghent GetTogether in 7 hours (yee-hah!) so I might not
respond to comments before Wednesday.
- Bertrand
Notes
-------
[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. Also, Blocks might not
be shipped with source code, in which case it will be easier to include a
Block's manpage in XML form with the block. And finally, having "magic"
filenames for such docs makes it easier to generate them.
