SPAM: Re: [OPEN-ILS-GENERAL] Writing an Evergreen manual

Tue Sep 25 09:21:06 EDT 2007

Pretty much agree with George.  I was thinking a static manual would be 
nice also, for the same reasons that you've cited (nice printing and 
document-version synchronization).  DocBook is one of the most popular 
formats, and is well established in the industry.  The flexibility of 
automated transforms to XHTML and PDF make it that much better. 

DocBook++
GNU_FDL++
Documentation_SVN_Branch++

A quick search also yielded a "DocBook Wiki" program 
(http://doc-book.sf.net).  It appears to allow you to edit DocBook's 
right in a wiki-style format.  It mentions integration with CVS for 
version tracking, but one of the demo's mentions also integration with 
SVN.  Might be worth checking out too.

In general, I completely agree with Dan.  It's rare that I don't ;).

--Don
PS: Although sent from my company-use e-mail address, the views and 
opinions expressed herein are my own and may not reflect those of my 
company.

Dan Scott wrote:
> 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 :)
>
>   