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

[Lori Ayre]

Sent from my iPhone 4

On Mar 5, 2011, at 2:47 PM, Dan Scott <dan at coffeecode.net> wrote:

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

Okay. It was named differently on the wiki which is why it wasn't  clear.
> 
>> 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.
> 
Okay. I guess I considered what was proposed (accept the draft provided as is and edit as needed) an acceptable community process. Am I missing something?  Are you suggesting a different workflow for documenting new development?

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

I see Robert is going to give Asciidoc a spin. Yay!  I tried to play with it in my Windows box but couldn't figure out how to get it going...
> 
>> 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.

Sounds like we have a degree of happiness working!
> 
>> 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.

I must be using the wrong language. When I say "incorporate the documentation into the software" I was referring to the code repository you mention above. This appears to be different from the repository that contains the official documentation now in Docbooks format that is managed by DIG. Maybe I'm the only one who is confused...so I'll just listen for awhile. 

Lori