Hi Berin,
On Mon, 20 Aug 2001 10:12:16 -0400, Berin Loritsch <[EMAIL PROTECTED]> wrote:
> The 1st order of business is the _requirement_ of both
> printable and browsable documentation. The Printable
> docs will be a very simple markup, with minimal graphics.
> They will have *no* navigation links. Browsable docs
> will be the current complex XML.apache.org format (which
> really needs revisiting). The Browsable docs will all
> have an extra link to view the printable version.
What do you mean by no navigation links inside the printable
documentation? If we generate PDF, we can have highlighted words which
are active links inside the PDF. When you print the PDF, the
highlighting disappears and looks like normal text. For an example
check-out the second page in:
http://xslt-process.sourceforge.net/xslt-process.pdf
> We need 3 documentation tracks:
>
> 1) Installation and Configuration
> 2) Using Cocoon (creating your own webapps)
> 3) Developing Cocoon (maintaining Cocoon/Cocoon architecture).
This sounds very good! I was thinking at exactly the same type of
documentation.
> I propose that for new documentation we use DocBook format.
> You will see examples in Avalon CVS (the Developing with
> Avalon documentation). The Stylesheets in the Avalon CVS
> can be adapted for Cocoon.
Why do we develop new stylesheets for DocBook? There is already a
project, DocBook-XSL, of Norman Walsh and many others, the DocBook
author, which has fairly extensive stylesheets. There are stylesheets
that generate HTML, XHTML and XML FO. The system is setup such that is
fairly easy to customize your own look and feel for the generated
output. I think we should use this rather than spend the energy on
creating our own stuff.
Take a look at:
http://docbook.sourceforge.net/
You need to look at the DocBook-XSL project.
> The URI space will be planned as such:
>
> cocoon2/ Welcome page and general overview--links to mailing
> lists, CVS, and distributions
>
> cocoon2/api The JavaDocs for Cocoon
>
> cocoon2/authors The list of author bios (linked from the documentation
> pages--like on Jakarta Avalon site)
>
> cocoon2/installing The installation and configuration documentation
>
> cocoon2/userdocs The user documentation (i.e. HowTo write your own
> webapps with Cocoon)
>
> cocoon2/developing The developer's docs on the architecture and design
> of Cocoon.
This looks good to me.
> There should be 4 FAQ documents:
>
> 1) cocoon2/faq.html Questions about Cocoon in general (what is it? why
> was it built? etc).
>
> 2) cocoon2/installing/faq.html Questions about installing and configuring
> Cocoon (XYZ doesn't work, what should I do?)
>
> 3) cocoon2/userdocs/faq.html Questions about how to do something in Cocoon
> (I need to serialize XML from a database, how?)
>
> 4) cocoon2/developing/faq.html Questions about maintaining Cocoon
> (I've spotted a bug and have a fix, how do I
> get it committed? Why is XYZ ThreadSafe?)
Should we try to use one of the Web FAQ tools out there? I especially
like the way the PHP documentation is setup (see for example
http://www.php.net/manual/en/functions.php). It allows external
contributors, not only commiters to add their own comments to the
documentation. It's a very powerful and loosely coupled way of
collaborating, especially on FAQs, and documentation examples.
Now I know we may not be very interested in having a PHP system
running on xml.apache.org, but it may be something to get us going
until we develop a Cocoon based system. We should just use the tool
that does the job, even if it's "not invented here" (TM) ;-).
I think the current way of managing the FAQ is making it slow for
updates and makes people think of alternative solutions. Just look at
the recent thread on cocoon-users, "reg c2 documentation HOW DO I", to
see what I mean. Even a simple process as sending an email with an FAQ
item to one of the committers for inclusion in the FAQ, may be a
process too much.
Greetings,
--
Ovidiu Predescu <[EMAIL PROTECTED]>
http://orion.nsr.hp.com/ (inside HP's firewall only)
http://sourceforge.net/users/ovidiu/ (my SourceForge page)
http://www.geocities.com/SiliconValley/Monitor/7464/ (GNU, Emacs, other stuff)
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
