[OPEN-ILS-DOCUMENTATION] Installation Documents from README files.

[Dan Scott]

Hi Steve:

On Sun, May 1, 2011 at 12:29 PM, Steve Wills <steve.wills at lyrasis.org> wrote:
>
> I heard today on IRC that there may be as many as 3 or 4 different install documents that get created for a given version of Evergreen.

Just three documents today.

> 1. the README file created by the developers
> 2. A Wiki page which may also be created by developers
> 3. A Web page.  I am a little confused about the difference between the Wiki page and the Web page.

No Web page currently exists. So that's how we only have 3 today.

> 4. A DocBook  DIG version that may be created independently but probably sourced from the README file at some point in time.
>
> I am wondering if my perception is accurate and, if so, what we can to to minimize version drift among these very important documents.
>
> I think I would suggest that we designate the README as the source of authority for this information and it gets used to spawn other versions.  Further, bugs found while using any version of these documents need to find their way back to the README, which then spawns all other revisions.  Is this reasonable?

Right, that was the quasi-suggestion I had made on IRC; we're cutting
over to Asciidoc as the source format for the README, which makes it
easy to generate HTML (and PDF, epub, etc), so I had suggested that
perhaps we should kill the wiki pages and start generating Web pages
automatically for the install instructions instead. I had also noted
that that leaves the DIG install documentation as its own island, but
at least it removes the drift between two of the three current
locations of install docs.

I should also note that the README has been created / maintained by
the developers historically, but (particularly with the adoption of
git) it doesn't mean that only developers can write and maintain that
content. Filing bugs, sending patches, or making pull requests from
other repositories are all welcome.