Hi Steve: On Sun, May 1, 2011 at 12:29 PM, Steve Wills <[email protected]> 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. _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
