←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
262 points jumpocelot | 3 comments | 10 Jul 25 15:01 UTC | HN request time: 0.552s | 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 #
Scubabear68 ◴[10 Jul 25 21:17 UTC] No.44525718[source]▶
In my experience, technical people tend to tag way too many topics with “simply”. It is usually best to get rid of the word.
replies(3): >>44525809 #>>44525975 #>>44531122 #
1. IshKebab ◴[10 Jul 25 21:45 UTC] No.44525975[source]▶
I agree. It usually seems simple to the author but it's bloody annoying when some documentations says something is simple and it actually isn't.
replies(2): >>44526356 #>>44533896 #
2. dctoedt ◴[10 Jul 25 22:23 UTC] No.44526356[source]▶
Fair. Context matters.
3. ar_lan ◴[11 Jul 25 16:13 UTC] No.44533896[source]▶
I refuse to use the word "simple" in my docs writing for this precise reason. I have come to view the word to seem condescending/elitist, even if that's not the intent.

If something is written as simple, but I as an entrant to something view it as not simple, I'm going to be severely discouraged - "if this is the simple thing, what is the hard thing?"

It's often an unnecessary adjective.