Documentation proposal

[Sylvain Hellegouarch]

Hey people,

Here are my thoughts about the documentation project. THose are also a summary
from our previous messages.

Goals
=============================

The documentation of a system or a product is as important than the coe of the
product itself. You may have the best product in the world, if nobody can refer
to some kind of good documentation, it will never be used.

CherryPy is simple but it still requires that we deliver good doc with it. Not
just a tutorial and some recipes but a comprehensive, up-to-date and clear
documentation about every aspects of the product.

This is the goal of our project.


Targets
=============================

People using CherryPy will be different, at some stage we will have :

* developers of the CP project itself
* users that build application atop CherryPy
* administrators that deploy CherryPy application

Those targets require different knowledge.

Developers need to know the details of the implementation of CP but without
necessiraly browsing the source code. They need some documens that exaplain the
architecture of CP. Documentation in this case would act as an API/architecture
reference.

Users only need to have a big picture of CP architecture but they should not
have to browse the source code to understand how CP works. We need to provide
them with the interface they will use and that's it. Besides that, they also
need a complete guide on how writing an application with CP.

Administrators only need to know how to deploy a CP application, what it
requires and what it will do.


Planning
=============================

We need to define a solid base before going any further.

1. Define the trusted people who are motivated to contribute
2. Define a simple document describing the rules we will follow to build the
project
3. Define exactly which tools we will be using (DocBook certainly but let's
all agreed on that)
4. Define the documentation structure
5. Start with a simple example and review it before going too far

- Sylvain





----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.

[Jos Yule]

Sylvain Hellegouarch wrote:
> Planning
> =============================

> 5. Start with a simple example and review it before going too far

While i don't have the time to put into writing the documentation, i'd
be interested in helping to 'debug' it (review).

I'm a pretty average user and can hopefully bring that view point to the
content of the documentation, and have some useful suggestions for edits
or direction.

j

--
jos yule
Digital Hyakugei

mailto:j...@theorganization.net
http://www.theorganization.net

jabber:hyak...@jabber.org
msn:hyak...@hotmail.com
yahoo:digital_hyakugei
aim:josyule
icq:295196397

[Remi Delon]

Well, this is the same process as for contributing code ... Speak up on
the lists/IRC, gain the trust of other people by showing that you know
what you're doing and then you'll get SVN write access :-)

> 2. Define a simple document describing the rules we will follow to build the
> project
> 3. Define exactly which tools we will be using (DocBook certainly but let's
> all agreed on that)
> 4. Define the documentation structure

Agreed. But again, for some of these, we don't need to re-invent the
wheel ... There's already plenty of existing stuff for Python itself and
we should take advantage of that (except that we'll be using DocBook
instead of Latex).

> 5. Start with a simple example and review it before going too far

Good idea ...

Remi.