←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
262 points jumpocelot | 1 comments | 10 Jul 25 15:01 UTC | HN request time: 0.208s | 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 #
mtlynch ◴[11 Jul 25 02:01 UTC] No.44527749[source]▶
I agree with you that these examples feel awkward

>This reads silly for another reason: websites don't... introduce things.

The way they're using "introduces" does feel awkward, but in general, it's fine to say that a website "introduces" something.

For example, the Homestar Runner website introduced the world to Strong Bad. Or Action Comics #1 introduced Superman. You wouldn't really say that the author of Action Comics #1 introduced Superman.

replies(1): >>44528958 #
1. perching_aix ◴[11 Jul 25 06:30 UTC] No.44528958[source]▶
Going 100% by vibes regarding this, but I feel "introduced the world to" / "introduced x to the world" being a very established phrase is what makes it overpower the awkwardness that's otherwise present.

For example, "Or Action Comics #1 introduced Superman." immediately feels more awkward, the reason it's not quite as awkward as RedHat's example is because it's in-context and doesn't explicitly mention "website", so one could conceivably mistake it for a magazine instead (which I take it probably was/is, an online one specifically).

Using "website" like this is like suggesting they're a publication or a periodical of some sort, which is true for some, but not in general (e.g. news sites?), making it weird.