Re: Documentation outline (draft)

Sorry it has taken me so long to respond to this. But it all looks great.

At 01:23 13/03/03, Felix Maeder wrote:
>Hi list
>
>With the goal to improve the lenya documentation I was thinking about a 
>new structure of the documentation and came up with a first draft of an 
>outline (attached as xdocs and html).
>
>The main change I would suggest is to abandon the separation of an 
>integrator's, an administrator's and a deveoper's guide.


This is fine by me and I think a wise decision. Let us create one good manual.

Please be careful about the use of the word "developer". I assume you mean 
people such as yourself who are adding to the Lenya java code. However the 
integrators and implementors are developers too.



>  The documentation is so high level that there's only a few things that 
> are aimed exclusively at the developer.


I am not sure who the documentation is aimed at but *please* spend the time 
to introduce things before you start talking about them. Not everyone has 
the same experience and so may not know what you mean by particular jargon.

>The real deleveloper's documentation is JavaDoc anyway.


Well I hope that was a joke, but I know what you mean.


>A user's guide (for the business user of the cms application) is no high 
>priority at this point because such a guide depends on the concrete 
>implementation (the real publication). That's why I left it out.


Agreed. We *might* create a specific publication for a newspaper, say, and 
create a user's guide as part of that sample publication. In fact I'd say 
that all the sample publications should be self documenting :-)


>The top-level structure looks like this:
>- Installation
>- Getting Started (How-to's)
>- Concepts and Best Practises


Hooray.

>- Components
>- Deployment and Administration
>- Proposals / Requests for Comment (RFC)
>- Related Topics
>
>
>
>Outline Lenya Documentation
>
>    * Installation
>        * Binary Version
>        * Source Version


We need to clarify system requirements. It looks like we need JDK 1.4, a 
recent tomcat, etc etc etc but in production I am still using JDK 1.3
This is important :-(

>    * Getting Started (How-to's)
an overview of the sample publications supplied with Lenya. Is there a 
"default" publication? oh.
>    * Customizing the default publication
>        * Change the look
>    * Creating your own publication
>        * Copy the default publication
>        * Some basic configuration
>        * Customize the navigation
>        * Further steps


>    * Adding a new doctype
>        * Create the directories
>        * Customize the sitemap
>        * Create the dummy xml
>        * Create the look (xhtml, xslt)
>        * Make the document editable
>            * With Bitfluxeditor
>            * With Xopus
>            * With HTMLFormEditor
>        * Configure menus, creator, publisher, scheduler

Hmmm. Something is worrying me about this section, but lets put that aside 
for now. Perhaps it is the word "doctype"....


This all seems really good. What seems to be missing is how the existing 
documentation fits in to this setup. There are (for example) lots of XML 
files. It is not clear how to use these - whether they are Lenya config 
files, or just one particular example of a sample publication.

I've volunteered to be a cvs committer for documentation if you'll have me. 
I am still very much a beginner, but perhaps that is what you need :-)

Alex McLintock



Available for java/perl/C++/web development in London, UK or nearby.
Apache FOP, Cocoon, Turbine, Struts,XSL:FO, XML, Tomcat, JSP
http://www.OWAL.co.uk/