Wiki Documentation Idea
christian
What if we had a wiki for each release? For example, we create a wiki,
docs.cherrypy.org/wiki/2.2 or something, that contains the
documentation for 2.2. When the time comes for 2.3, that wiki is
copied to to /wiki/2.3, we look at the WikiPageIndex, or whatever that
is called for the particular wiki we decide on, and go through updating
the things that have changed from 2.2 to 2.3.
Meanwhile, www.cherrypy.org could have links to 2.2 and 2.3 docs in the
main menu. People who care about 2.2 could check there and people who
care about 2.3 could check there.
That way, the wiki is also somewhat "versioned" with major releases.
Thoughts?
Christian
http://www.dowski.com
Remi Delon
cherrypy-devel as well ...
> What if we had a wiki for each release?
Yeah but that means that for each new release we have to manually copy all
the recipes from the previous wiki ... This can seem like a lot of work,
especially if only a few recipes have become obsolete...
I have another proposal for a documentation system which I'll describe in a
separate post.
Remi.
Remi Delon
documentation system:
The system would be a blog-like tool with tagging:
- Each "article" (ie: recipe, howto, ...) would correspond a blog entry
- Each article can be tagged by various tags. Sample tags would be "CP2.0,
CP2.1, CP2.2, Unofficial, Apache, Database, Templating, ..."
- People could add comments to each article
- Anonymous users could:
- Write new articles (which would automatically be tagged "Unofficial")
- Write comments for all articles
- Admin users could do anything:
- Write articles
- Update articles (based on comments for instance)
- Delete articles
- Change tags of articles
- Delete comments
When a new CP version is released we just add a new tag called "CPX.X",
which no article has by default. We then go through each article and add the
tag if the article is still valid for this version.
The home page of the documentation would show a hierarchical list of tags
(and maybe sub-tags) with corresponding articles.
Sylvain and I happen to already have the right tool for this. We could setup
a live site in a few days and people could start contributing.
What do you think ?
Remi.
PS: Two notes:
1-
> being able to use a "real" editor can be very nice (as opposed to being
> stuck with a text area in a web browser). I've done bulk find/replace
> several times along the way, which I wouldn't have been able to do with
> some wiki packages.
Well, the blog-like system would store articles in a database, so we
couldn't use normal file-handling tools ...
For find/replace, there will be a "Search" feature that will allow us to
find all occurences of a certain string. But we'd then have to manually
replace them ... Another option would be to use SQL (or a small python
script making some SQL calls) if we have a really tedious task to do ...
2-
Of course, we still need some API docs generated from comments in the code
but that's a separate issue ...
Remi.