cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <bdelacre...@codeconsult.ch>
Subject One-page documentation plan?
Date Mon, 18 Nov 2002 08:54:09 GMT
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.

Mime
View raw message