Kevin Dangoor wrote:
I think that there are enough needs for open source software
documentation that are not readily dealt with by the existing (open
source) tools, that I want to start up a new project.
The goal of Docudo will be to create an open source, TurboGears-based
software project documentation tool. It won't be a be-all, end-all
CMS. It won't make your toast in the morning. But it *will* provide
you with a sane mechanism for collaborating on and keeping up with
documentation on for open source projects.
What's the goal for Docudo relative to other projects? Or, what
projects do you see as complimentary?
I've thought some about this too, and imagine several pieces fitting
together:
* Emphasize docstring content for reference documentation.
* Docstring content points directly to code.
* Use index-like documents that point into the documentation generated
from docstrings. This documentation serves as an overview and usage
guide, but isn't comprehensive. But it is also not expected that you
would start reading from a generated module or class index.
* Permission system makes editing of these documents fairly easy, and
does not require full Subversion access for a person to contribute on
this level. Not quite a fully-open system (like a wiki), but more like
ask-and-you-will-receive. Does not allow for creating documents, just
editing them.
* Allow user contributed documentation, with open editing (like a wiki).
These are marked as such, and this is an appropriate place for things
like recipes and tutorials. These documents may move over to the
general documentation as well. Users can add new documents here. Login
is required, but with self-signup.
* I don't think user contributed documentation needs to be structured
like a wiki. I think a simple index (maybe with categories) is
sufficient. Maintaining wiki-style navigation is not useful or needed
for software projects.
* Allow for inline comments. This is as open as possible, so long as it
keeps out spam. I'm not sure if the comments should be always present,
present in a parallel part of the site that is linked from each page, or
what. If the comments are inline, it's a lot easier to process and
integrate them into documentation.
That's the public side, at least. The backend side is something else
again. I think Restructured Text with some custom roles and an
indexing/resolution stage (Bob mentioned this in a previous thread) can
handle the relations in documentation well. I think Pudge's docstring
rendering is passable -- it needs some work, but it's no worse than
anything else I have seen. All the document extraction systems have
problems in different ways :(
--
Ian Bicking / [EMAIL PROTECTED] / http://blog.ianbicking.org
