[OPEN-ILS-DOCUMENTATION] Single-sourcing install docs (was: Re: 2.0 documentation problems)

[Dan Scott]

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