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

[Martha Driscoll]

I almost always follow the HTML instructions simply because it's easier 
to have a browser window open under a terminal window.  If I'm 
installing and trying to read the README, then I have to stop what I'm 
doing to view the README or have a second terminal window open.

I'm a little confused about who HTML readers are vs. README readers. 
Are they not the same people?  I would hope that both versions are as 
close to identical as possible.  If you have to put a warning on the 
HTML version that says to follow the included README, then what's the 
point of having an HTML version?

I liked the "wget, un-tar, cd path/to/source" steps and miss them on the 
new HTML page.  What's the down-side of keeping that in the README? 
Taking a quick look at the phppgadmin and rt-4.0.1 README's, they both 
start by saying where the source is located and how to untar them. 
Basic steps for most people, but I don't think I've ever seen a README 
without them.  Both websites link to the plain text README or INSTALL on 
their respective githubs.

--
Martha Driscoll
Systems Manager
North of Boston Library Exchange
Danvers, Massachusetts
www.noblenet.org

On 10/26/2011 1:12 PM, Yamil Suarez wrote:
> 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
>
>