On 5 March 2011 14:17, Lori Bowen Ayre <[email protected]> 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. _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
