Hello, Note: I am sending this email to both the dev list and the DIG list.
I have been working with my intern Travis Lilleberg on ways to improve the EG README and the HTML version of the EG README, as part of our attempt to have a single source of installation instructions. A lot of the suggested changes that Travis' and I have come up with are meant to increase the usability for helping those that are *only* following HTML README instructions, and therefore not following the README included with the EG source. For example, we are considering adding instructions on how to "wget, un-tar, cd path/to/source" the EG source files, which used to be mentioned in the older online installation instructions.
Our concern is that if we add these changes that mostly only help HTML README users, we are decreasing the readability of those that are only following the downloaded README file.
- One simple approach is to just put a warning on the HTML README suggesting that the downloaded README be the one to be followed closely for installation. That way developers only have to focus their efforts to maintain the regular README for one type of audience, i.e. local readers and not both local and online readers.
- Instead, we can just add a quick note about running "wget, un-tar, cd path/to/source" on the HTML README side only, or even add a dedicated preamble to the regular README meant for those only using the HTML version (though visible to all readers).
- A whole new approach is assuming the EG 2.1 official docs will reuse the HTML README content (which is one of my DIG to-dos), then DIG folks like myself could add one of the suggested fixes above (or others approaches) to make the official version friendlier to online only readers. That way developers continue to focus only on the regular audience.
I wondered what the community thinks of these ideas? Thanks in advance, Yamil _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
