RE: [docbook-apps] Producing Open Source Software

I too would love to get some more background on how the PHP project got to where it is.

As I mentioned before I’ve done some work with other open source projects and they, while valuing some amount of documentation, are rabidly in the Wiki world.

Since my day job is to produce documentation for these projects in DocBook, I would like to be able to push some of the content back to the projects without having to re-format it for their wikis.

From: Karen Schneider [mailto:kgschneider@gmail.com]
Sent: Friday, March 06, 2009 8:51 AM
To: docbook-apps
Subject: Re: [docbook-apps] Producing Open Source Software

Admittedly, getting the XML right is sometimes a bit of an issue for
the newbies, but they learn. Very quickly. Simply because their
commits fail to build. And are 2 steps produce all the output needed
to fix it.

PHP is one Docbook example I've been looking at from all angles because it does seem to work. I'd be curious to hear how it got there (not just what the steps are but incentives, encouragement, mandates, motivation, and also ways to keep people focused on producing in Docbook -- because there are other methods and I have observed discussions in another project where the pull is to produce in the wiki).

Part of the solution appears to be:

* Thoroughly documenting how to produce documentation
* Organizing the documentation so it is very thin-sliced (you can successfully produce a very small section of the documentation)
* Using -- and if necessary, creating -- tools that fit in the authors' workflows
* Incentives (such as acknowledging authors, and even the subtle use of second person -- "viewing your changes")
* Easing the way (and ensuring stylistic consistency) by providing clear templates ( http://doc.php.net/php/dochowto/chapter-skeletons.php )

Hidden behind this are the discussions, people, etc. who moved this project into a documentation mindset. Part of the decision to Docbook had to be the need for translation, but even beyond that was a decision that documentation is essential to the project. Such incentives exist (it produces better code, it encourages wider participation). My guess is there was one or several people who were key to making documentation part of this project's culture.

docbook-apps message