cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: One-page documentation plan?
Date Mon, 18 Nov 2002 12:42:10 GMT

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


Mime
View raw message