←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.418s | source
Show context
perching_aix ◴[10 Jul 25 20:05 UTC] No.44524926[source]▶
Might be just my ESL self being silly but these examples both read horribly:

> For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than

Even without reading the next bit I just knew that no, this does not read better. The insertion of "a site for reference material and other resources" just makes this sentence horrible to follow period.

> "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence.

This reads silly for another reason: websites don't... introduce things. Website owners might. Also, I feel it should say "reference materials" not "reference material".

replies(4): >>44525075 #>>44526287 #>>44527749 #>>44531165 #
1. Chilko ◴[10 Jul 25 22:16 UTC] No.44526287[source]▶
That sentence structure of the first example ('subject, long tangent, conclusion') is very common in the German language (and a major annoyance for me when reading German), so perhaps the author has that background?
replies(2): >>44532202 #>>44535875 #
2. Hendrikto ◴[11 Jul 25 13:56 UTC] No.44532202[source]▶
Notably, because German has more articles and conjugations, this writing style is very clear and easy to follow in German, at least to native speakers.
3. oasisbob ◴[11 Jul 25 19:11 UTC] No.44535875[source]▶
It's also a very typical sentence structure taught in US English. I learned it around 7th grade where there's a huge push to teach formulaic ways to use commas properly instead of just sprinkling them everywhere in run-on sentences.

Googling now, that usage is often referred to as using commas to offset a non-essential clause.