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


2009/3/6 Karen Schneider <kgschneider@gmail.com>:
>> 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
>

For me, the motivation is to have good documentation. I use PHP all
day and if the manual is wrong, being able to correct it seems like a
great way of contributing to it.

The whole process is open to peer-review. Every commit is emailed to a
mailing list. Anyone can read it and comment on it.

The developers are not always the documenters. I think that's an
important point. They KNOW how it works at a level that is WAY to
complicated for the user. In the main it is PHP users who document
PHP. Sure a LOT can also develop PHP (by "develop", I'm talking about
the C code which makes PHP, not PHP scripts).

And compared to all the XSL stuff that was around and the literally
hours it would take to run, the new build tools are a significant
improvement. Almost to such a point that we can have all the manuals
in all the languages generated daily, and on the docs server, twice
daily if needed.

The same tools are now also building the PEAR documentation (PEAR -
PHP Extension and Application Repository pear.php.net).

Same tools and 2 significant DocBook projects. All done in a fraction
of the time it took for the OpenJade tools.

Richard.

-- 
-----
Richard Quadling
Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
"Standing on the shoulders of some very clever giants!"


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