[OPEN-ILS-GENERAL] Writing an Evergreen manual

[Dan Scott]

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