Red Hat Technical Writing Style Guide

(stylepedia.net)

265 points jumpocelot | 1 comments | 10 Jul 25 15:01 UTC | HN request time: 0.291s | 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]▶

>>44525543 #

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. Cthulhu_ ◴[11 Jul 25 11:56 UTC] No.44531122[source]▶

>>44525718 #

Same in spoken word; I don't know if this is a regional (western European, expat-English) thing, but a lot of people will interspers their spoken sentences with "basically" and "actually" a lot. It's gratuitous and more of a verbal tic than something that adds to their sentence.

But maybe I'm overthinking it too much. I prefer reading.

↑