[OPEN-ILS-GENERAL] Timeline question: Writing an Evergreen manual

[Deb Bergeron]

Dan,

A question I forgot to ask--what is the timeline for this document 
creation process?  Are you envisioning having a complete document 
completed by the time 1.2 release is completed?

Thanks,

Deb

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 :)
>
>   

-- 

------------------------------------------------------------------------
Deb Bergeron <mailto:bergeron at macalester.edu>
CLIC <http://clic.edu>, System Administrator User Support
1619 Dayton Ave. Suite 204A, Saint Paul, MN  55104

T: 651.644.3878   C:651-487-7609    F:651.644.6258

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-general/attachments/20070926/c2d36880/attachment.html