bits crossposted:
http://tm.teresco.org/forum/index.php?topic=1800.msg4763#msg4763Feeping creaturism.
"Shows the relevant modification to the file" -- unintuitive, as it will often be hidden amongst a bunch of other files changed in the same commit. (Unless we mandate that each commit change only one file, an idea I dislike.)
"Shows all modifications to the file" -- The user will have to find the correct commit to look at the DIFF. Often apparent if the user knows the date the change was made, but sometimes not.
"Shows the old version of the file" -- Either this would require some very clever coding from Jim (or whoever was tasked with implementing it.), or the collaborator making note of the update changes would have to find the SHA for the old version of the file. Some of us aren't that well versed in GitHub, and still submit updates the old-fashioned way, by emailing to Jim or another contributor. Either that's more work that's potentially outside the expertise of a particular contributor, or more work for Jim or whoever.
I think looking at GitHub (and loading stuff into WPTedit) is by its nature more suited to the Power Users -- and those who have the inclination and the know-how can find the appropriate part of GitHub on their own... via "TM on GitHub", their own Browser History, or however. Putting the task of finding the link to a relevant commit on the data contributors, IMO, just adds more busy-work, complication,
(and further chances for things to go wrong), for too little gain.
If our pursuit of perfection becomes too relentless, it will soon become a headache of its own.
If the description is not clear, the actual solution is asking on the forum. This might work but it's painful for everyone.
Or referring to GitHub, as you mentioned, though that's not for everyone. For casual users, yes, asking on the forum is probably the way to go if things are unclear. I think think there's much of a practical way to avoid the process being painful at some point , somewhere. So let it be painful. We just gotta find a way to make the least amount of pain the most tolerable.
--
I think the old CHM conventions, the "mad-libs" of how to phrase updates wording, are overall a very good benchmark to strive for.
They can be found at the bottom of
this page (search for "Newsworthy news entries").
A couple excerpts:
Relocated route (in middle of route):
Pennsylvania US 220: Removed from Main Street and 5th Avenue, and relocated onto a new northern Georgetown bypass, between US 23 and PA 70.
(mentions both ends of the new part, that is, the intersections/places where the old and new alignments meet) and both the old and new routes
Don't refer to "the new route" or "the new end". Instead, say what the new route is.
Sure, even I'll admit that writing these out can get tedious at times. But proper, descriptive wording in the updates entries can go a long way toward establishing clarify.
