Red Hat Technical Writing Style Guide

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".

It might be dialectical, but in American English, I think “reference material” sounds fine. (Maybe “material” in this context is uncountable or collective or something)

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?

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.