Documentation reloaded
amix
CherryPy is really the best web-framework out there, but there is one
problem: the documentation!
One could write more articles, update the wiki, write more into the
book etc., but I don't think it will change anything in the long run.
Here are my proposals:
An updated API (borwser like):
I have used different frameworks and the easiest ones I have tried is
those that come with an updated API. An example: frameworks in Java are
very complex, but yet you can find all the information you need. This
isn't due to long documents describing how the framework(s) work, but
because of JavaDoc. Python also has a GREAT documentation of the API.
Same goes with PHP. An updated API is essential.
Why not bring something JavaDoc/PythonDoc into CherryPy and have
documentation written as you write the code? A browser for that
documentation is also essential.
More tutorials:
The tutorials in CherryPy are great, but it would be really cool to
have many more of them.
Tutorials are easy to understand and they give the developers some code
they can run and reuse, they are brilliant on documenting on how the
system works.
Some extra tutorials could be how to code own filters, how to use the
different template systems, how to use CherryPys filters etc.
I know there is a book underway and it is really great, but I think
generally it would be cool to automate the documentation system.
Another thing:
To make CherryPy more professional, wouldn't it be smart to separate
the website into different parts:
- One "static" that has a presentation, download area, book, official
documentation, API browser etc.
- The wiki part (the one now), where users can document etc.
amix [http://amix.dk]
Remi Delon
> CherryPy is really the best web-framework out there, but there is one
> problem: the documentation!
Agreed :)
> One could write more articles, update the wiki, write more into the
> book etc., but I don't think it will change anything in the long run.
> Here are my proposals:
>
> An updated API (borwser like):
> I have used different frameworks and the easiest ones I have tried is
> those that come with an updated API. An example: frameworks in Java are
> very complex, but yet you can find all the information you need. This
> isn't due to long documents describing how the framework(s) work, but
> because of JavaDoc. Python also has a GREAT documentation of the API.
> Same goes with PHP. An updated API is essential.
>
> Why not bring something JavaDoc/PythonDoc into CherryPy and have
> documentation written as you write the code? A browser for that
> documentation is also essential.
I agree as well.
A tool that seems interesting is http://pudge.lesscode.org/
It seems to have support for attributes as well (which I'm not sure
PythonDoc has).
> More tutorials:
> The tutorials in CherryPy are great, but it would be really cool to
> have many more of them.
> Tutorials are easy to understand and they give the developers some code
> they can run and reuse, they are brilliant on documenting on how the
> system works.
> Some extra tutorials could be how to code own filters, how to use the
> different template systems, how to use CherryPys filters etc.
> I know there is a book underway and it is really great, but I think
> generally it would be cool to automate the documentation system.
>
> Another thing:
> To make CherryPy more professional, wouldn't it be smart to separate
> the website into different parts:
> - One "static" that has a presentation, download area, book, official
> documentation, API browser etc.
> - The wiki part (the one now), where users can document etc.
Yes, I also think that a clear separation between what's official and what's
not is essential (we could even have 2 different sites).
I think it makes sense if the official documentation (apart from the API
browser) goes in the CP book.
The non-official one could be a wiki.
Remi.
Kevin Dangoor
> > Why not bring something JavaDoc/PythonDoc into CherryPy and have
> > documentation written as you write the code? A browser for that
> > documentation is also essential.
>
> I agree as well.
> A tool that seems interesting is http://pudge.lesscode.org/
> It seems to have support for attributes as well (which I'm not sure
> PythonDoc has).
PythonDoc *might*. The infoset mentions having a "variable" subject:
http://effbot.org/zone/pythondoc-infoset.htm
The reason I'm leaning toward PythonDoc at the moment is:
* it sticks to source parsing
* it allows you to set nice metadata about function parameters, etc.
* output should be easy to work with via the infoset
Pudge, of course, has the ability to generate a whole site. (For
TurboGears, I generate the site based on a fairly simple script that
I've customized along the way... parts of that script were actually
merged into Pudge at one point, but I stopped that effort.)
> > Another thing:
> > To make CherryPy more professional, wouldn't it be smart to separate
> > the website into different parts:
> > - One "static" that has a presentation, download area, book, official
> > documentation, API browser etc.
> > - The wiki part (the one now), where users can document etc.
>
> Yes, I also think that a clear separation between what's official and what's
> not is essential (we could even have 2 different sites).
>
> I think it makes sense if the official documentation (apart from the API
> browser) goes in the CP book.
> The non-official one could be a wiki.
This has been basically my approach. There's the "Documentation
Playground" on the wiki, where people can write what they want. As I
approach the TG0.9 release, I'm going to pull things from there,
refine a bit and stick it in the official docs.
Kevin