Topics to start with

[Sylvain Hellegouarch]

Hi folks,

Now that we have this list, let's start on builiding a solid documentation
project.

IMO, we need to discuss some topics before starting writing anything. Here are
some of them that I think are important :

* Goals and targets of the documentation of CherryPy
We need to define what we want to acieve and what and who are our targets.

* Tools
Once we now where we're going to and who we're talking to, we'll be able to
decide which tool is the best. It seems DocBook will be our ground but let's
discuss that a bit more.

* User interaction
It's a bit part of the first topic but more specificaly, do we want users to be
able to comment (like the PHP doc) or will it be more static?

* Structure
Once we have defined our goals and targets we will be able to start thinking of
a structure.

I am pretty sure there are some other topics. Let me know.

- Sylvain



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

[Lukas Linhart]

Hi,

>* Tools
> Once we now where we're going to and who we're talking to, we'll be able to
> decide which tool is the best. It seems DocBook will be our ground but let's
> discuss that a bit more.

I'm voting for subversion repository with documentation, and modular docbook,
one file per chapter and one root file. (BTW, I'm using XXE, suitable tool it
is)

>* User interaction
> It's a bit part of the first topic but more specificaly, do we want users to
be
> able to comment (like the PHP doc) or will it be more static?

I think static pages with (moderated) user comments is best.

Sorry for short answer, will post additional comments soon.

--

Lukas "Almad" Linhart

[:: http://www.Include.cz/ ::]
[:: Including Your wishes ::]
[:: PGP/GNUPg key: http://download.almad.net/pubkey.asc ::]

[Remi Delon]

> Now that we have this list, let's start on builiding a solid documentation
> project.
>
> IMO, we need to discuss some topics before starting writing anything. Here are
> some of them that I think are important :
>
> * Goals and targets of the documentation of CherryPy
> We need to define what we want to acieve and what and who are our targets.

Well, this should be the "official" (ie: authoritative) documentation
for CherryPy ...
To start with, I think it should contain:
- a tutorial
- a list of recipes
- an API reference
- a FAQ

I think we can just import the current content from the Wiki to start with.

> * Tools
> Once we now where we're going to and who we're talking to, we'll be able to
> decide which tool is the best. It seems DocBook will be our ground but let's
> discuss that a bit more.

>>I'm voting for subversion repository with documentation, and
>> modular docbook,
>> one file per chapter and one root file.

Agreed.

> * User interaction
> It's a bit part of the first topic but more specificaly, do we want users to be
> able to comment (like the PHP doc) or will it be more static?

If people want to submit comments/fixes/contributions, this should be
done through the Trac ticketting system, just like for source code.
There is already a component called "cherrypy-documentation" in Trac.

> * Structure
> Once we have defined our goals and targets we will be able to start thinking of
> a structure.
>
> I am pretty sure there are some other topics. Let me know.

Remi.


PS:
> Great but could you add a prefix like cherrypy-docs to all
> messages to and from that list please?

This should be done now.

[Sylvain Hellegouarch]

Selon Remi Delon <re...@cherrypy.org>:

> Well, this should be the "official" (ie: authoritative) documentation
> for CherryPy ...

I agree. We need to be able to ell the user "Go see that page, this is the
reference!". But it means being complete AND clear!

> To start with, I think it should contain:
> - a tutorial
> - a list of recipes
> - an API reference
> - a FAQ
> I think we can just import the current content from the Wiki to start with.

We'll need to have a discussion on that one. The current docs we have as you
said does not always match the state of CP's source code and therefore we would
need to go over all the recipes we already have. This is needed anyway but I'm
not sure that it's a good idea to start from bits and pieces.

I'd rather start from scratch with a really aim and above all a ground on which
we can rely to evolve the doc later on.

That being said, it might be interested that we propose a couple of existing
project that we can use as models (for instance, I quite like the Qt
documentation).

>
> If people want to submit comments/fixes/contributions, this should be
> done through the Trac ticketting system, just like for source code.
> There is already a component called "cherrypy-documentation" in Trac.

This is nice but not so user friendly. I'm not for user comments anyway because
they are usualy misleading. So let's keep Track ticketing system for now. It's
better.

>
> This should be done now.
>

Thanks

[Remi Delon]

>>To start with, I think it should contain:
>> - a tutorial
>> - a list of recipes
>> - an API reference
>> - a FAQ
>>I think we can just import the current content from the Wiki to start with.
>
> We'll need to have a discussion on that one. The current docs we have as you
> said does not always match the state of CP's source code and therefore we would
> need to go over all the recipes we already have. This is needed anyway but I'm
> not sure that it's a good idea to start from bits and pieces.

Right. We should only import the "quality" content from the Wiki and
ditch the rest.

> I'd rather start from scratch with a really aim and above all a ground on which
> we can rely to evolve the doc later on.

Well, if you write it then it's up to you to decide whichever is easier
for you :-)

> That being said, it might be interested that we propose a couple of existing
> project that we can use as models (for instance, I quite like the Qt
> documentation).

I don't think we need to look that far ... IMHO, the python docs are
great and we should model after them: http://docs.python.org/
They've got all the sections we need:
- tutorial -> tutorial
- module index -> API ref
- documentation python -> documenting cherrypy :-)
- what's new in python-2.4 -> what's new in cherrypy 2.1 :-)

The first chapter of the tutorial is even called "Whetting Your
Appetite" ... It's as if they knew about CherryPy already :-)

Remi.

[Sylvain Hellegouarch]

Selon Remi Delon <re...@cherrypy.org>:

> Right. We should only import the "quality" content from the Wiki and
> ditch the rest.

Good. We'll do it that way :)

> Well, if you write it then it's up to you to decide whichever is easier
> for you :-)

It is indeed a good point. ;)

> I don't think we need to look that far ... IMHO, the python docs are
> great and we should model after them: http://docs.python.org/
> They've got all the sections we need:
> - tutorial -> tutorial
> - module index -> API ref
> - documentation python -> documenting cherrypy :-)
> - what's new in python-2.4 -> what's new in cherrypy 2.1 :-)

Hmmm. That's true and it will be more consistant accross Python documentation.

> The first chapter of the tutorial is even called "Whetting Your
> Appetite" ... It's as if they knew about CherryPy already :-)

eh eh :)