On Jan 18, 10:15 pm, Jonathan Lundell <jlund...@pobox.com> wrote:
> I've been working a little on a proposal for some new cookbook sections, one
> per chapter, that provide a roadmap to the web2py source that's relevant to
> the chapter.
There are two dangers in documentation:
1) Too little
2) Too much
"Too much" can be bad for at least two reasons: it is a lot of work to
maintain (need many people), and; it becomes difficult to maintain a
cohesive document design in a collaborative environment. Ironically,
even though the web2py project has been accused of "too little
documentation", in truth we already suffer from the symptoms of "too
much". There is gold buried in the web2pyslices.com site, things that
should already be in the book, but are not because the sites are
separate, and it requires significant effort to merge information into
something useful. The solution is not to create more, but to first
improve what we have.
However, having said that, I do think you make a valuable point about
improving the knowledge transfer of the web2py source code itself.
That job can only be properly performed by someone such as yourself,
who knows the code well. There are not *that* many of you, but the
numbers could grow if you write such a document.
I guess the point I am making is that we must be careful to try to
make the greatest impact with the least amount of work.
There are three forms of documentation that emerge (I am including a
lot of extra detail for other readers of this post that may pass by):
a) The book, often called the "Developer's Guide" in other development
tools; this is for the person new to web2py that wants to learn how to
get stuff done in the fastest possible way. It won't carry the full
API, and nor should it, because of (b)
("The book", here: web2py.com/book)
b) The programming API, often called the "Programmer's Guide" in other
development tools, which would presumably be made up of docstrings
harvested directly from the source code
(Epydoc, here: http://www.web2py.com/examples/static/epydoc/index.html).
c) Tutorials, Cookbooks and Howtos
(web2pyslices, here: http://web2pyslices.com/main/default/index)
I really like your suggestion about a guide to the web2py source code,
because it seems that dramatic leverage is available through that
route to get a lot more hands on deck for the development work. I am
less keen on calling that a cookbook. Calling it a tour guide would
be better, if I understand what you're aiming for, and you could break
the hegemony that the cookbook metaphor holds over the programming
space. Enough cooking already! Let's do sights and sounds!
I don't know what the quality of the API documentation is like ([b] in
my list above), because I spend most of my time on (a), and frankly,
the book has been enough for me in the vast majority of situations
(dir() for everything I need more information about!). The web2py
book is a great landmark in the project (not "ingredient"!).
I think I am in favour of your suggestion of putting references to
source units inside the book itself. I would probably suggest that
the format of that inclusion be little more than a list of applicable
source files per section, rather than the level of additional detail
you demonstrate. To add further discussion would create more
maintenance work for the documentation, and would detract, I feel,
from the purpose (and quality, assuming no duplication) of the API
documentation. Epydoc provides a space for writing module-level
comments, and my gut feel is that the higher-level description of the
source code itself should appear here. Perhaps a link from the book
chapter to the Epydoc page for that module? For instance, for the
DAL chapter, we can link immediately to the module-level Epydoc API
documentation right at the start of chapter:
http://www.web2py.com/examples/static/epydoc/toc-web2py.gluon.dal-module.html
And then you and the other core developers could attack the in-source,
docstring documentation, and in particular the module-level docstrings
with expanded explanation and discussion. If you go to the link above,
you'll see the module-level text that is there already; it's a good
start, but room for the very improvement you have demonstrated in your
post.
My ZAR0.02 :)
