IRC meeting on July, 19th 2005 - Summary

[Sylvain Hellegouarch]

Hi everyone,

I will try to give a good summary of what has been said regarding the CherryPy
doc questions we discussed during the meeting.

If you feel like you need to expand a point, feel free to open a new discussion
on the cherrypy-docs list.
> Main topics:
>
> - Static doc : the book currently being written (and available on the
> SVN repository) : is the TOC allright? who could give a hand to write
> one or a few sections? what output format would like to get (HTML and
> PDF are already planned)?
> - Dynamic doc : define what exactly we are looking for : recipes? code
> snippet? what else?
> - Regarding recipes : should we have a set of official recipes that have
> been checked and are maintained by the CP team itself and then keep a
> place for user's recipes?
> - Regarding the wiki : should we drop it completely? change it? should
> we go for a PHP-doc-like system (static doc but allows user coments)?

First of all we all agreed that the documentation was becoming an important to
point to update from now on, specially since 2.1 stable will be out soon. It
has been stated quite clearly as well that we would not have time to finish the
book before releasing 2.1 stable.

We have drilled down the number of documentation components to three:

- a manual
- api doc
- recipes

The manual will offer :

- a tutorial to start up with CP
- more advanced sections for a deeper understanding of topics such filters,
config system, session, administration, api reference, etc.

The api doc will be available through docstrings extracted from the source code,
thus we need to start documenting in a comprehensive way the code (following PEP
257 http://www.python.org/peps/pep-0257.html)

We will define a set of common and handy recipes that a few people will review,
edit and make sure they match the version they aim. Users will have the
possibility to submit new recipes through the cherrypy-users or cherrypy-docs
lists. We *may* also provide an easier way for users to send us recipes through
a web form. This needs to be further thought.

Basically most of the work to gather such different components has already been
made through the official book available now here
(http://www.cherrypy.org/wiki/CherryPyBook : please remember this book is still
at its early stage!). We need to add a section for official common recipes
reviewed by the core team. It will be added soon.

So we need to focus now on writing most of the book. We invite everyone to
download the book (docbook format) and update it as he/she can. Then submit
what you've done to an editor who will check it in.

Finally, it has been decided to lock up the wiki so that only a few trusted
users will have the possibility to edit it. This decision was extensively
discussed but almost everyone agreed that it is too hard to keep the wiki up to
date due to all the recipes that are not upgraded nor well tested. We hope that
by providing a set of common recipes and also through the book, users won't
feel left out. In any case the cherrypy-users and cherrypy-docs lists are there
to listen to your requests of course.

Another reason to lock the wiki was too stop the spam!

Now we will still keep Trac because of its tight integration with SVN and we
keep a wiki itself because it is makes life easier for its editors to submit
content.

During the next few weeks we will need to clean it up and to remove/edit old
recipes that are not correct.

So to recap what we need to focus on :

- writing the book
- writing docstrings
- cleaning up the wiki

I think that is pretty much all we said but again feel free to send any feedback
you need.

- Sylvain



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