OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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.


--
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| kgs@esilibrary.com
| Web: http://www.esilibrary.com
| Be a part of the Evergreen International Conference, May 20-22, 2009!
| http://www.solinet.net/evergreen


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]