Re: [docbook-apps] Producing Open Source Software

[Richard Quadling <rquadling@googlemail.com>]

2009/3/6 Eric Johnson <EMJOHNSO@progress.com>:
> I too would love to get some more background on how the PHP project got to
> where it is.
>

The oldest documentation I could find in the CVS tree is here :
http://cvs.php.net/viewvc.cgi/phpfi/doc/doc.html?revision=1.1&view=markup&sortby=date

That was committed nearly 13 years ago. A LONG time before I started on it.

As you can see, it is html and the content gives you some idea of
where PHP started.

The PHP Doc mailing list would be a good place to start getting more info.

>
>
> 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.
>
> --
> | 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



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