I believe I've raised this concern before, but the disconnect between the READMEs in the tarballs, the wiki install instructions, and the official documentation worries me. On the developer side, we're likely to update the wiki and the READMEs, so when we run into problems that people have we now also have to ask what source of documentation they're using to rule out discrepancies in the docs.
Given that we're using AsciiDoc for the READMEs, I'd really like to see a single-sourced solution for the install documentation, and would like to propose that the READMEs be the authoritative source, with the wiki pages and official docs generated from those. Dokuwiki doesn't accept AsciiDoc formatting, unfortunately, but we could either write a simple syntax transform from AsciiDoc -> Dokuwiki (for our limited purposes), or possibly drop HTML directly into Dokuwiki, or drop HTML pages right onto the website (with a pointer to where the install doc source lives for those who want to submit changes). Similarly, AsciiDoc -> DocBook needs some cleanup to be integrated into the official docs, but I'm sure those steps could be automated as well and I would be willing to help that effort. If we have just one source for install instructions, then all eyes (tech writers and developers and users) will be on the same info, and this critical area of the docs should be able to be improved across the board without duplicating or triplicating effort. -- Dan Scott Laurentian University _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
