[OPEN-ILS-DEV] Suggestions for improving Evergreen's HTML README for online readers

[Yamil Suarez]

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