[OPEN-ILS-DOCUMENTATION] [OPEN-ILS-GENERAL] DIG version of Acq docs (was: Acquisitions and Serials Documentation Drafts Now Available)

Sat Mar 5 17:29:33 EST 2011

First of all, a big thanks to Dan Scott. This is awesome stuff! except for the fact that he has reduced documentation turn-around expectations from my lazy goal of several months to a speedy 25 minutes on a Saturday morning!;-)

I updated the github repository:

Added a new asciidoc folder and added the asciidoc file here:
https://github.com/rsoulliere/Evergreen-DocBook/blob/master/asciidoc/2.0/stafftasks/acquisitions_module_GPLS.txt

Docbook XML is in the repo here:
https://github.com/rsoulliere/Evergreen-DocBook/blob/master/2.0/stafftasks/acquisitions_module-GPLS.xml

I went ahead and added to official 2.0 documentation and here:
http://docs.evergreen-ils.org/2.0/draft/html/acquisitions-module_GPLS.html

To get it to fit into the documentation I had to make a few minor changes such as:

- change the "article" tags to "chapter" to fit into the document as a chapter of a book (I don't think Asciidoc allows converting an asciidoc document to "chapter" but that is not a big deal at all)
- clean up the first several lines to fit into the chapter type.
- change version reference for Docbook to 5.0 (asciidoc uses 4.5) Perhaps docbook version can be set in asciidoc configuration files?

There is some follow up cleanup which must be done to these documents. For example:

Lots of semantic markup will need to be added. (of course this can be expected since asciidoc could be expected to handle presentation elements but would have some difficulties with semantics.)

It does not use indentation to make it easy for editing differentiating code blocks. Use of indentation must be added later (again this probably should be expected and can be added later)

Overall, this is an exceptional way to process documents quickly as Dan has demonstrated and gets a document into presentation shape.

I am all for getting the information into the documentation out to the community, and cleaning up later so this works wonderfully for me.

Not sure if expectations that Dan will process all the rest of the docs at 25 minutes a pop is fair to him... On the other hand, he did establish this 25 minute precedent.;-)

Regards,
Robert

Robert Soulliere, BA (Hons), MLIS
Systems Librarian
Mohawk College Library
robert.soulliere at mohawkcollege.ca
Telephone: 905 575 1212 x3936
Fax: 905 575 2011
________________________________________
From: open-ils-general-bounces at list.georgialibraries.org [open-ils-general-bounces at list.georgialibraries.org] On Behalf Of Lori Bowen Ayre [lori.ayre at galecia.com]
Sent: March 5, 2011 2:17 PM
To: Dan Scott
Cc: Evergreen Discussion Group; open-ils-documentation at list.georgialibraries.org
Subject: Re: [OPEN-ILS-GENERAL] DIG version of Acq docs (was: Acquisitions and Serials Documentation Drafts Now Available)

Thanks, Dan.  So the document you've converted called "Acquisitions Module"  corresponds to the document ESI/GPLS developed called "Acquisitions Documentation."

Seems to me there is no harm in getting this into repo as is so that (as you both are saying) people will have access to it quickly AND anyone can suggest changes as we find things that need to be changed or find ways to improve what ESI/GPLS has provide.

That said, ca we also expect you to convert these documents from ESI/GPLS?  At 25 minute a pop, I know that's asking a lot.

Acquisitions Functions in Acquisitions Module
Serials Documentation
Workflows and Diagrams - Serials and Acquisitions

I guess I should verify my assumption first....

Am I correct in assuming that once converted to asciidoc, everyone is happy including:

1. developers who can make it part of repo
2. Evergreen users who get it with their code
3. DIG who can make it part of DocBook, and
4. ESI/GPLS who can claim credit for doing a great job even if we just take it as is and work from this document without undertaking a more formalized 30-evaluation period????)

I personally am liking the principle that this would establish which is that we take documentation that developers have provided and incorporate it into the software as is recognizing that we've got procedures in place where fixes and improvements can be made so why not get it out there as soon as we can to as many people as we can.  Early and often as they say.

Lori

On Sat, Mar 5, 2011 at 7:20 AM, Dan Scott <dan at coffeecode.net<mailto:dan at coffeecode.net>> wrote:
On Fri, Mar 04, 2011 at 11:28:40PM -0500, Soulliere, Robert wrote:
> Well... in regards to suggested revisions by DIG the important factor to remember is that there is probably only a handful of Evergreen acquisitions experts in the entire world or those with enough experience to revise what has been created. I am not sure who if anyone currently actively involved in DIG would be able to provide expert level content revisions. That being said, If a group could be formed to review, test and perhaps merge the best of both documents that might be one approach. However, given the voluntary nature of DIG, it might take a while to review the content given that the acquisition document from GPLS is 45 pages alone. During the content review phase among a small group of acquisition specialists, if we decide to go this route and can round up these specialists, could review the documents in word / open office /basic text format until a final version can be merged into once version. (We could move the document into wiki format as suggested by some, but it seems like an awful lot of work to convert to that format for review of such a large document.)
> Once content is refined, it can be forwarded to the DocBook conversion team (me) to be converted to DocBook XML and  added to the official documentation.
>
> A second approach would be to convert and add both documents side by side  "as is" into the official documentation to allow quicker publication and inclusion in the official Evergreen documentation. Then, the documentation could be reviewed by the larger community and refined gradually through feedback by the community and users of the documentation. It could then be eventually merged into one near perfect document through gradual evolution based on feedback from users. I would lean towards this approach and would expect the documentation "as is" to get into the official docs within several months. The other approach might take longer time to reach publication depending on the number of perfectionists on the content review team.
>
> The GPLS documentation looked pretty good and will help a lot of users and I am sure both documents have very useful and critical information for Evergreen users trying to get their heads around acquisitions.

Absolutely - thank you GPLS and Equinox! In the ideal world,
documentation written for the project would be created and maintained in
the format that the project itself uses for its official documentation,
but we'll take whatever we can get, right?

To that end, I have attached a quick AsciiDoc port of the "Acquisitions
Module" document, along with the corresponding HTML, PDF, and Docbook
output that AsciiDoc creates. It took me about 25 minutes to convert
this by hand from a copy/paste of the entire PDF text. The resulting
document is missing the screenshots, because extracting the screenshot
images from PDF (or Word or OpenOffice) is more work than it's worth -
but for the most part, those are superfluous anyway, as you'll probably
have the staff client in front of you when you're using the
documentation.

Interestingly, the PDF and HTML produced by this process is arguably
more useful than the original PDF, as the table of contents entries
actually link to the corresponding sections in the document. That said,
some of the highlighting of menu items is lost, and none of the
cross-references to other sections within the text are active links
(although they weren't active links in the original PDF either).

We could check the AsciiDoc source into a repo so that anyone could
follow the changes line by line as corrections come in - and if the
community wanted to start adding screen shots, those could go in the
repo too. Good fun!

--

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=
Lori Bowen Ayre // Library Technology Consultant
The Galecia Group // www.galecia.com<http://www.galecia.com/>
(707) 763-6869 // Lori.Ayre at galecia.com<mailto:Lori.Ayre at galecia.com>

<mailto:Lori.Ayre at galecia.com>Specializing in open source ILS solutions, RFID, filtering,
workflow optimization, and materials handling
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message.  If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited.  If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.