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

[Lori Bowen Ayre]

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> 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
(707) 763-6869 // Lori.Ayre at galecia.com

<Lori.Ayre at galecia.com>Specializing in open source ILS solutions, RFID,
filtering,
workflow optimization, and materials handling
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20110305/4a07b345/attachment.htm