How to check phrasing and word choices?

Question

I'm a native speaker of French, and even though I think I have a rather good level in English, I always try to keep an open mind. (I learned English by absorbing from a lot of sources: TV, movies, video games, etc.) The problem with an open mind is that people always try to stuff things inside.

Recently I was writing some documentation for a tool we sell, and on two specifics instances, a colleague corrected what I wrote by changing a big part of the sentence. When I asked what motivated the edits, he answered that he found my sentences too "written" (i guess they didn't roll off the tongue? or that they were not really elegant). I'm ready to admit my english may be a bit stilted at times, but here i'm not really sure it's the case.

Specifically, would you say that his is a valid point? Here are the two edits in question, first my version then his.

---

• In our example we would for example check the cache statistics with the powershell commandline for AppFabric, but you can use whichever tool you’re most comfortable with
• In our example we would for example check the cache statistics with the powershell commandline for AppFabric, but feel free to use the tool you fancy

---

• This information is not readily available without knowing the ins and outs of every part of the program you’re using
• This information is not easily accessible without knowing the ins and outs of every part of the program you’re using

---

But to use my question as a launching pad towards something less specific, how can i find out if a turn of phrase is pleasant/good/valid? In this particular case i resorted to a simple google fight; it worked (kind of) for the "readily available" vs "easily accessible" which seemed to support my phrasing but this solution breaks down quickly when you don't have a readymade saying versus another. Are there other metrics than the "gut feeling" me and my colleague are resorting to?

Answer 1

Re "How can i find out if a turn of phrase is pleasant/good/valid?", writers.stackexchange will serve if you phrase your questions properly. Per its faq, one may ask about "Non-fiction, technical, or scholarly writing" and "Copywriting", among other genres, so long as you are not asking about "strictly interpreted correctness of English grammar or syntax rules".

In the first collegially-rewritten example, "In our example we would for example" is quite clumsy. Consider instead "In our example, one can check cache statistics with an AppFabric powershell command, but use whatever tool you most like".

Re the second example, advice to prefer readily available to easily accessible seems wrong. That a phrase is frequently used carries no weight if it's the wrong phrase. The information in question evidently is readily available, and the actual problem is it isn't easy to access without knowing all about some program.

Answer 2

I'm not sure this question is exactly "on-topic", but anyway...

Firstly, per my comment above, I suggest OP doesn't take too much notice of this particular colleague. Having said that, it always worth asking native speakers for their opinion, even if you don't always take their advice.

Another possibility is to use Google Books. In the case of OP's second example, my gut instinct was to prefer OP's readily available over the suggested "improvement" of easily accessible. A quick check confirmed that the former is indeed significantly more common. A few more seconds looking at some of the actual usages seemed to further confirm my suspicion that readily available is used more in respect of information, and easily accessible more in respect of raw materials and such.

Answer 3

One issue that hasn't been addressed in this discussion is the balance of a pleasing style versus the general accessibility and clarity of the informational content.

In principle, elegant prose is a desirable commodity; in practice, elegance (in particular, the avoidance of repetition) sometimes needs to be sacrificed in favour of terminological consistency and the avoidance of any possibility of creating ambiguity.

That is particularly so with a technical document, where readers may find themselves puzzling over whether object 1) is actually the same entity that is being referred to by the near-synonyms 2) and 3), especially if no diagrams are included that would enable them to clarify the point. It's better to stick to the same terms unless there is absolutely no chance of misinterpretation on the part of the reader -- and even then, such deviations ought to be used sparingly. Unless you're writing something like The Dummy's Guide to PowerPoint, where (I presume) the author is given an explicit brief from the publisher to write his explanations as entertainingly as possible, you will probably want to establish a fairly consistent tone as well as consistent terminology.

All that being said, where repetitiveness can be eliminated without sacrificing the more important objectives already mentioned (and I'd certainly agree with jwpat7 that "In our example we would for example check the cache statistics" is one of those situations), it should be.

So for this kind of documentation, you could sum up the ideal approach thus: "Write as inelegantly as you must; otherwise, as elegantly as you can".