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

Tue Sep 25 10:34:56 EDT 2007

Just adding my voice to the multitude -- I think a more structured manual
would be a Very Good Thing indeed.  For those folks on Ubuntu (and possibly
Debian), there're lots of Docbook related items in apt, including Docbook's
definitive guide.  Time to get reading.

jf

On 9/25/07, Murphy, Sally <smurphy at georgialibraries.org> wrote:
>
>  I'm also all for this idea, not only for version control (which is
> certainly a good thing), but also because I find a manual easier to use than
> the wiki.
>
>
>
> I'll be happy to contribute by writing a section and/or prettying up stuff
> from the wiki – I've already been compilling everything I can find on
> OpenSRF (from various blog posts and the like), so organizing that into a
> single document might be a good place for me start.
>
> I could also work on some of the "Core Tasks" section, if the outline on
> the demo below is the one you want to stick with – I'd suggest adding a
> "troubleshooting" section, too, for things like "Receipts only partially
> printing" and "xulrunner crashing" and the like – I can also add to that as
> I learn more about fixing the software.
>
>
>
> What would be **really** nice would be if we could also put the parts of
> the manual that concern the staff client into a Help file that could be
> packaged with it.  Especially for the troubleshooting section.
>
>
>
> -Murphy
>
>
>
> *Some say the world will end in fire and ice.  Others say it will be
> segfaults.*
>
>
>
> -----Original Message-----
> From: open-ils-general-bounces at list.georgialibraries.org [mailto:
> open-ils-general-bounces at list.georgialibraries.org] On Behalf Of Don
> McMorris
> Sent: Tuesday, September 25, 2007 9:21 AM
> To: open-ils-general at list.georgialibraries.org
> Subject: SPAM: Re: [OPEN-ILS-GENERAL] Writing an Evergreen manual
>
>
>
> 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.
>
>
>
> Don McMorris Jr.
>
> | Technical Specialist
>
> | Equinox Software, Inc. / The Evergreen Experts
>
> | phone: 877-OPEN-ILS (673-6457) x709
>
> | email: dmcmorris at esilibrary.com <mailto:dmcmorris at esilibrary.com>
>
> | web: http://www.esilibrary.com
>
>
>
>
>
>
>
> 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<http://open-ils.org/%7Edenials/testbook.pdf>
>
> >   * XHTML: http://open-ils.org/~denials/testbook.html<http://open-ils.org/%7Edenials/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<http://open-ils.org/%7Edenials/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 :)
>
> >
>
> >
>

-- 
http://libgrunt.blogspot.com -- library culture and technology.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-general/attachments/20070925/3901f04d/attachment-0001.html