Christian Boos wrote:
Bottom line:Improving the documentation system for Trac should motivate us to make Trac better at writing documentation, not prompt us to ditch Trac in favor of another tool for doing that job.
This was discussed in depth a while ago, but I will sum up the key points here.
1) A wiki exists for communication, taking quick notes, and to act as a general buffer between both developers and the community. It is _not_ a system to write good technical documentation. We have optimized both our wiki syntax and editing system to match these intentions IMO, so I don't consider this a problem. Some documents which need rapid editing from many people will remain better suited to being in the wiki, an example being the proposals that live under TracDev. Our actual documentation is another story. One big reason to move to ReST files in Subversion is we gain easy branching, thus warding off the current insanity with 0.1[012]/* page names and such. It also allows us to move to a submit-a-patch workflow as we do with code. Documentation is just as critical as any other part of the project, and as much as I like community involvement, it has become clear through experience that wikis do not work for our needs. ReST has an existing and powerful documentation toolchain that very closely matches our needs, so I think it is a logical fit. We will indeed be "eating our own dogfood", as the newhelp system designed for this will be exposed to projects using Trac for their own documentation needs (with the t.e.o methodology and toolchain serving as an example of how to use it).
Now to get back to the original topic at hand, I am happy with Sphinx and I think we should use it for our toolchain. The TOC and index systems are very nice and easy to use. I played around a bit with the autodoc extension, and it works quite nicely for pulling docs in from the source code, and makes it easy to add manual tweaks here and there.
I currently see things being broken into 4 main doc trees: guide (user docs), admin (administration guide), install (install process), and api or dev (developer reference and tutorials).
--Noah
signature.asc
Description: OpenPGP digital signature
