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

[Murphy, Sally]

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

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

> 

>   

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-general/attachments/20070925/30523d43/attachment-0001.html