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
_______________________________________________
OPEN-ILS-DOCUMENTATION mailing list
[email protected]
http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
