On September 24, 2007, Dan Scott sent the following email to the open-ils-general list:
Hello: The wiki is a great resource for quickly searching and adding information, but as a formal body of documentation it leaves something to be desired. Say, for example, that you wanted to print a nice cataloging and circulation manual - right now you would be hard pressed to pull the wiki pages together in a print-worthy format. In addition, the wiki pages have a nasty way of changing to reflect the current version of the code - so if you have Evergreen 1.0 installed on your site, and the wiki contributors are all working with the cutting edge 1.4 development release, then you might have to dig back through old revisions of each page you read to find the docs that apply to your release of Evergreen. So, as the Evergreen 1.2 release is rapidly approaching, I would like to get a more formal documentation project underway to augment the wiki. I propose that we adopt the DocBook XML standard for technical documentation (as is used by PHP, MySQL, PostgreSQL, and myriad other projects) and the associated XHTML & PDF transforms to start producing "The Book of Evergreen". If you want to see what the output looks like out-of-the-box, you can see a sample at the following URLs: * PDF: http://open-ils.org/~denials/testbook.pdf * XHTML: http://open-ils.org/~denials/testbook.html And if you haven't seen what DocBook XML source looks like, you can see the source for these sample documents here: * http://open-ils.org/~denials/testbook.xml (Please note that I whipped up the table of contents for the manual in a few minutes; it's not meant to be an exhaustive overview or anything resembling a final product! I think the wiki would be an ideal place to work out the details of a quality ToC.) As you can see, the DocBook structure is semantically rich and pretty easy to work with. I'll try to flesh out the source with some more expressive sections in the near future so there will be some templates to work with for things like code samples, commands, links, etc. I'll also try to put together some documentation for how to put together the XHTML and PDF transforms. Assuming that there's a consensus about moving forward with this model for the manual, I don't think writing in DocBook should be required for those who don't have the time to learn DocBook; we should be able to accept good doc contributions in plain text or other formats, and convert it to DocBook on the contributor's behalf. For licensing purposes, I suggest the GNU Free Documentation License 1.2 (http://www.gnu.org/licenses/fdl.txt) with no invariant sections and no required cover text. Any contributions to the manual would have to be contributed under this license. This also means that we would have to seek explicit permission from contributors of the documentation that has already been contributed to the wiki if we want to include any of that in the manual. I hope that we will be able to add a "doc" repository to svn.open-ils.org, if the good people of Evergreen are willing. At the same time, I hope to be able to start working on getting the infrastructure in place on the open-ils.org site to regularly build and publish the manual. Fresh documentation is always a rewarding sight for a documentation writer. This process may also be useful for providing integrated online help for the staff client - even if, to begin with, the help consists of simply the manual and isn't contextual at all. So, to summarize: 1) The wiki isn't going away, it's still an extremely useful tool for quickly dumping documentation and notes and for collaboration. 2) DocBook is the de facto standard XML schema and publishing tool set for open source projects, so we will be able to capitalize on the work others have done before us. 3) Documentation licensing will fall under the GNU FDL. 4) There's work to be done to get this all up and running, but we've made it this far without a manual; another few weeks aren't going to kill us :) 5) There's plenty of ways to contribute to the documentation project; from commenting on the manual table of contents, to editing, to writing, to creating prettier CSS for the XHTML, to implementing searchable XHTML on the open-ils.org site, to setting up "user notes" functionality for each XHTML page (although - warning - user notes require a massive amount of effort to maintain in the PHP and PostgreSQL projects!). If you think you might be able to help, I'll welcome your contributions - no matter how big or small. Of course, this is just a proposal. If everyone is happy with the wiki as-is, that's fine too. I would think you're all crazy - but that's fine :) -- Dan Scott Laurentian University
Others looked upon his proposal, and judged it good. Thus began the Evergreen manual.