←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
265 points jumpocelot | 1 comments | 10 Jul 25 15:01 UTC | HN request time: 0.238s | source
Show context
dctoedt ◴[10 Jul 25 20:59 UTC] No.44525543[source]▶
Parts of this are excellent. I teach a contract-drafting course for 2L and 3L law students. Some aren't good writers. When I mark up their work, I can provide them with links to specific points in the RH guide.

Some parts aren't so great. Example:

> EXAMPLE[:] Remote users can connect to network resources simply by authenticating to their local machine. IMPROVEMENT[:] Remote users can connect to network resources by authenticating to their local machine.

It's not at all obvious that you improve the sentence by omitting "simply." You lose some compressed information: in this case, an implication that alternatives to local authentication might be more complex. This implication might be significant, to some readers and certainly to the writer.

replies(2): >>44525718 #>>44531595 #
1. williamdclt ◴[11 Jul 25 12:56 UTC] No.44531595[source]▶
Depending on where the emphasis is (which there is none in written form), it could be read as:

"How to connect to network resources simply? By authenticating to their local machine" (which I think is how you interpreted it)

or "How to connect to network resources? Simply by authenticating to their local machine" (which I think is what was meant)

The ambiguity itself is a good enough reason to not use this form. If the former was meant, say "the simplest way to connect to network resources is ...", otherwise just drop the "simply" as suggested