The docs are on https://docs.redhat.com/
at worst a regwall.
For the record I think Red Hat shouldn't put those behind a login, but that's a different argument
It's not a login. It's a login with an active subscription. Are those article that valuable that they can't provide it for everyone with a @company.com address that has >n licences?
Pure speculation, but I'm guessing they view the knowledge base as part of "support" (or like level 1 or something), which is why they're so restrictive. I think they greatly underestimate the number of people like us though that already use RHEL but don't want to bother with accounts because we can get by without it, but would benefit from having the access. They don't seem to understand the friction their policies create, and I think that's deeply unfortunate.
I do wish the knowledge base wasn't behind a log in, and Red Hat isn't perfect (there are plenty of things that either don't get updated for new RHEL releases and end up cut, or aren't comprehensive enough), but they do contribute a ton to documentation that benefits everybody.
* "Best practices": Aspects that tangibly improve docs quality. Usually backed up by experimental data or overwhelming consensus.
* "Conventions": Arbitrary decisions that don't clearly improve docs quality one way or the other, except for the fact that they improve consistency, and consistent docs are easier to use.
When everyone in the room has this shared understanding, TW style guide conversations often go much faster and smoother.
It's a convention that most documents use a monospaced courier or monospaced grotesk as that typeface.
[EDITED to add:] I agree with the general point about distinguishing best practices from conventions, though. (But there are also intermediate possibilities. "Best practice for us because it fits with conventions we've become used to". "Best practice for us because of some peculiarity of us or our work, even though for other groups it might not be so good".)
Almost everything in there falls under the "best practices" bucket and there is little discussion of "conventions". If I did it again today, I would try to provide lots more justification and evidence for each guideline.
The upside is that authors focus their limited time/energy on the edits with the highest ROI. E.g. if the author only has time to either A) make the content more scannable or B) use Oxford commas everywhere, I would much prefer that they spend their cycles on A. This doc also reduced friction at review time. When some proposed new content didn't meet my quality bar for whatever reason, I would point the author to specific sections of this doc and ask them to revise their draft based on these guidelines.
During a code review, a request to fix a race condition is much higher priority than a name improvement. I'm arguing that TW style guides need a similar type of distinction.
I can pick out specific examples of best practices versus conventions in the Red Hat guide if it's still not clear.
The most reliable non-fine-tuned method I have seen is to do many, many passes over the doc, instructing the LLM to focus on only one rule during each pass.
Looking forward to your model/product!
P.S. https://www.gov.uk/guidance/style-guide/technical-content-a-... also looks useful
I recently produced a bunch of migration guides for our project by pointing Claude 4 Sonnet at my poorly structured Obsidian notes (some more than 5 years old), a few commits where I migrated the reference implementation, and a reasonably well-maintained yet not immediately actionable CHANGELOG. I think the result is far from top-notch but, at the same time, it is way better IMO than nothing (nothing being the only viable alternative given my priorities): https://oslc.github.io/developing-oslc-applications/eclipse_...
And here are its style comments: https://gist.github.com/stevelandeydescript/a586e312c400769b...
I don't plan to release the code, since I don't really want my docs to be written in this voice. But it doesn't feel entirely unhelpful, as long as I'm personally curating the changes.
The only part that throws me for a loop is in the Grammar section, which contains a mix of best practices (like "Prefer active voice to passive voice") mixed with basic rules about subject-verb agreement. The former is what I would expect to see in a Style Guide, while the latter is, I dunno...what I would expect as a basic requirement for passing high school English?
It just feels like for the level of fluency presumably required for a Technical Writer, basic grammar rules should be well understood and not need to be explicitly stated.
They got lost in the details.
I think it would be better to separate the advice as you suggest. Opinionated, or organization-specific, advice in one section and grammar in another.
Ensuring active voice and how to use possessives with product names is style.
"Who vs. Whom" is grammar.
My qualm is that a "Style Guide" is about explaining "There are multiple ways to do this correctly, but this is what WE prefer." For example, "Prefer American spellings of color/favorite over British colour/favourite, etc."
But with basic subject-verb agreement, it's a requirement of the language and not really up for debate. If your subject doesn't agree with the verb in number and gender, IT ARE WRONG.
[0] https://www.oxfordinternationalenglish.com/common-english-gr...
I’m very confused about what you are talking about, when
> > There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here.
per this comment:
https://news.ycombinator.com/item?id=44524290
As you mention what is or isn’t up for debate, why do you keep bringing up to debate something that is explicitly referenced but not discussed or addressed by TFA? The author already beat you to the punch by opting not to debate that point, and that’s the one you specifically want to talk about?
Are you fishing for red herring? Color me confused lol
I reckon this is just a poorly picked example on your end, because the guide explicitly states the following about that:
> There are two forms of agreement: subject-verb agreement and pronoun-antecedent agreement. Subject-verb agreement is pretty rudimentary, and is not discussed here.
Regardless, sometimes (oftentimes?) technical documents are written by people who are not actually technical writers. A good number of those will also have a native language other than English. And in a lot of high schools, passing the English class is really not a very high bar, especially when failing people en masse is not really an option. You can only coerce people to learn a language so well.
E.g. I am not surprised to read "Distance to the server is one of the factors that affects latency."
This one seems a little much. I've used this term in work writing within the past week (not in official documentation, but I do also write official documentation). I tried to look up what the acceptable alternatives are (since Section 4.6 doesn't specify one for that rule), but it seems most possible alternatives already have other, distinct meanings: https://english.stackexchange.com/questions/282282/near-univ...
Definitely not something I'd force onto others either though.
There's a lot of terminology around just mental illness that we have decided to leave in the past. And, a lot of it is for good.
One benefit of changing our language is we get a second chance. We can be more specific, more fine-grained, or more accurate. For example, sanity check is vague. If it's a bound check, we might say bounds check. That's more accurate. If it's a consistency check, we might say consistency check.
We want our language, particularly in technical pieces, to be both inclusive and precise. What I mean is, we want it to include every thing it should, and nothing it shouldn't.
For example, in Medical literature you'll often see the term "pregnant person" or "pregnant people", or even "people who may be pregnant". At first glance, it seems stupid. Why not just say "women"? Women is imprecise. There's a variety of people who would not identify as a woman who may be pregnant. If they get, say, a form with that verbiage they might mark "no, I'm not a woman". But they SHOULD mark "yes, I am a pregnant person" or "yes, I am a person who may be pregnant". It doesn't even just include transgender individuals - it also includes people born intersex, or people born without a uterus who do identify as a woman. There's women who may be pregnant and women who may never be pregnant, just as there are people who do not identify as women who may be pregnant. The word "woman" is then imprecise, confusing, and includes people it shouldn't, as well as excluding people it should.
This way leads to people writing blog posts about firing workers they don't employ because they used gender non-neutral language in technical posts.
>"Avoid superlatives in job titles and descriptions, especially problematic terms such as "guru", "ninja", "rockstar", or "evangelist"."
At a past job, it was actually embarrassing to introduce some of my colleagues in meetings as shit like "Data Guru" and "Marketing Guru".
(I'm sure we can skip the 100,000th argument about the rest of the section).
> 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".
>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.
All of these had in-house printshops, so would have had some style guides even if just to provide consistency for internal use.
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.
My brother is an interior designer who has done lots of work for hotels. He says that as an interior designer, people typically only notice your work if you’ve done it badly.
If you use a decently designed hotel room you don’t think much of it, but if it’s got problems like badly laid out space, even if you can’t quite put your finger on it, it feels “off”.
If a reader doesn’t have any opinions on a technical article and got the information they were expecting, then it’s probably well written.
When I write technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally as possible.
[0] https://www.stylemanual.gov.au/ [1] https://docs.divio.com/documentation-system/
freedomben•9h ago