Having read the new thread [TurboGears] Documentation/tutorial, it looks like the effort for working on documentation is quite high (you have to work on a low file and DVCS level to contribute).
I always liked the way how easy it is for everyone to deal with Django documentation, especially djangobook where you can make annotations for every paragraph and all that online. I guess a possible improvement (and also a cool feature for Pyramid) is a documentation system that is usable online for everyone, but still integrates with the DVCS approach: A website that displays the docs, but enables editing each paragraph in-place. It has its own hg repo behind, so if somebody starts editing, a new hg branch is created and if editing is done, a pull request is automatically filed on bitbucket. Merged by a docs maintainer afterwards, the new docs are shown instantly. This would also introduce a new way to easily improve documentation on a specific topics across multiple pages and different documentation for different versions: That's just branches and tags. Remember Django's "This document describes Django 1.2. For development docs, go here"? We can just make a drop box that shows entries like "current version", "2.0" and so on and for people currently working on the docs on how to integrate with Apache, there is "apache-overhaul". If the people working on "apache-overhaul" are finished with their improvements, they just click the "Submit doc branch as pull request" and that's it. Like the "parallel wiki for improving ...", but solving more problems at the same time. Web-based, light-weight, fun to use. And, most importantly, not too hard to implement. I know that there are Python wrappers around GIT (http://gitorious.org/git-python) which work quite well and I'm sure there is an equivalent for hg (as it is itself written in Python). On 16/01/11 14:42, Christoph Zwerschke wrote: > Am 16.01.2011 15:13 schrieb bvdb: >> This ML also seems not to be a good place to discuss these details - >> maybe there is a TG wiki for works like this (including a discussion >> module)? > > We tried using a Wiki for TG docs in the past, but the contributions > were few, of varied quality, and we had difficulties with spam etc. Also > it was difficult to get the Wiki docs in sync with new versions. We > probably made it too complex by using separate wiki namespaces for draft > and official and for the different versions, but OTH if we had used only > one namespace, it would have gotten a mess too. After that experience, > the TG2 docs were then created with Sphinx and stored in a repository, > but that created a hurdle of people to contribute, and the docs in the > reop are still of varied quality. > > This problem can only be solved by somebody stepping up and investing > some serious time as a docs manager for TurboGears, coordinating help > offers and regular doc sprints until the docs are in shape again. > > -- Christoph >
signature.asc
Description: OpenPGP digital signature
