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

[Dan Scott]

On 5 March 2011 14:17, Lori Bowen Ayre <lori.ayre at galecia.com> wrote:
> Thanks, Dan.  So the document you've converted called "Acquisitions Module"
>  corresponds to the document ESI/GPLS developed called "Acquisitions
> Documentation."

The filename of the document as posted was
"the_acquisitions_module.pdf", so I dropped the definite article when
it was named.

> 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.

Well, IMO, documentation that institutions pay to have written for
would ideally be developed as part of the community process, the same
way that the software itself is developed as a community process.

> 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.

I was attempting to demonstrate that 1) AsciiDoc is not hard and 2)
it's a possible primary source format for documentation writers of any
kind - whether contracted or volunteer or as part of your job - to
contribute to the official Evergreen documentation. I see that the MS
Word docs were added yesterday, which is way better than just PDF
(thanks!) - but making it easy for the DIG to integrate the docs into
the official documentation should be a goal.

I would be thrilled if someone else gave AsciiDoc a spin; as it is, I
probably won't have time to tackle this for a few days. Note that
while I said that screenshots were superfluous, AsciiDoc can handle
them quite easily - so if, say, Equinox or someone else wanted to try
converting one of the other docs to AsciiDoc, it's an option.

> 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 don't know if everyone is happy (one can always hope), but having a
format that can more easily be converted to Docbook seems like a win
to me.

> 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.

I'm not sure I understand this -  if by "the developers" you mean
Equinox, it's actually a tech writer at Equinox who wrote this
documentation. And the docs don't get incorporated into the software -
the contributed docs get incorporated into the docs. (Well - I would
like to see some of the docs live in the code repository and
single-sourced with the official documentation - README and install
docs and release notes and the like - but that's a subject for a
different thread and day). Arguably, the acq docs shouldn't need to be
converted and incorporated, they should just be an integrated part of
the documentation process in the same way that Equinox's development
work is part of the Evergreen software development process. But, after
all is said and done ... again, a huge thanks to GPLS for ensuring
that this gap is being filled, and to Equinox for being able to create
this content.