9 ms·
Red Hat Technical Writing Style Guide
- freedomben 1y agoWow, this is a really terrific guide. It's quite long, but it's long because of it's breadth, not because of being overly verbose (IMHO). I particularly appreciate the clear explanations and large number of examples that really help make the concept more concrete. I think this is quite broadly useful even for people that don't work for Red Hat.
- Cthulhu_ 1y agoYeah it reads like one to file away if I ever end up doing a lot of technical documentation. In this case, it's a guide that is aimed at an army of people (dozens? Hundreds? I don't even know, Red Hat has 19.000 employees) writing documentation as their day job. That is, I wouldn't be at all surprised if just the number of people writing documentation for RH is more than the number of engineers we have at my current employer (one of the major energy companies in the Netherlands).
- ban2ly 1y agoSeems useless, as Red Hat does not write documentation
- curt15 1y agoRed Hat has some of the most professional documentation of any distro. E.g https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/10-beta/ https://docs.redhat.com/en/documentation/red_hat_enterprise_...
- bauruine 1y agoMuch of it is behind a paywall though. I manage more than a hundred licenced RHEL machines, was an RHCSA and RHCE with a company mail but I'd have to ask someone in my org to give me access. I just blocked access.redhat.com on kagi. F you.
- worthless-trash 1y agoMost of the 'docs' are not behind the paywall, you're mixing up the KCS / FAQ's. The docs are on https://docs.redhat.com/ https://docs.redhat.com/
- bauruine 1y agoI didn't mix it up but most of the time I stumble upon redhat.com it's KCS (access.redhat.com) articles. Yes it's not "documentation" but if it's worth to create an article because that many people have the same issue I'd say you could add it to your documentation as known issues.
- worthless-trash 1y agoI dont think that google is indexing that without a login/subscription though. TIL.
- SSLy 1y ago> paywall at worst a regwall.
- bauruine 1y ago"You need an active subscription" is paywall for me.
- freedomben 1y agoYou manage over a hundred licensed RHEL machines but don't have an active subscription to access.redhat.com? Somebody is doing something terribly wrong in your org. How do you open support cases without that, or even manage the subs? For the record I think Red Hat shouldn't put those behind a login, but that's a different argument
- bauruine 1y ago
- freedomben 1y agoYes agreed, and they also extensively write and maintain man pages distributed with common FOSS software, and they are some of the best man pages I've ever seen. They are also freely contributed to the upstream projects so that the entire Linux ecosystem benefits. 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.
- kaycebasques 1y agoLooks solid. My gripe with most technical writing (TW) style guides (this one included) is that they mix best practices with conventions: * "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.
- lelandfe 1y agoI’m not sure I see the upside. Do you have an example you like?
- dsr_ 1y agoIt's a best practice to set commands that are to be typed literally in a different typeface. It's a convention that most documents use a monospaced courier or monospaced grotesk as that typeface.
- gjm11 1y agoUsing a monospaced typeface for that purpose isn't only convention; it reflects the fact that when those commands are typed literally, it will be in a terminal which almost certainly itself uses a monospaced typeface. I think I'd say that setting literal command text in a monospaced face is a best practice. [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".)
- pseudalopex 1y agoThe convention is used also for strings entered in a proportional font such as an address bar. I think the primary reason for the convention is most fonts where all characters are distinct are monospaced. But terminals being monospaced typically contributed surely.
- david422 1y agoThis seems like one of the perfect use cases for AI. Have the AI ingest the style guide, and then comment on your written work to point out where your work does not adhere to the style guide.
- kaycebasques 1y agoLots of people have tried it. The problem is the sheer number of rules in a typical technical writing style guide. I continue to believe that a fine-tuned model is the way to go, and I made a lot of progress on that front, but I learned firsthand how labor-intensive feature engineering can be. 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.
- golergka 1y agoOne agent and some hard code to extract doc diffs with relevant code, parallel agents for different rule groups, tool agent to look up existing patterns and related material in the codebase, consolidator agent to merge the comments and suggestions, that’s how I would do it, for the first version at least. All of them fine tuned, ideally.
- smarx007 1y agoI had moderate success using https://www.iso.org/ISO-house-style.html https://www.iso.org/ISO-house-style.html converted to markdown and narrowed to the guidelines starting with "Plain English" and ending before "Conformity and conformity-related terms" (plus a few other rules up to and including "Dates"). A quick estimate puts the whole Markdown document at 9869 tokens - quite manageable. I generally prefer the style of the Microsoft Writing Style Guide but ISO house style is the only one that fits nicely into a prompt. Looking forward to your model/product! P.S. https://www.gov.uk/guidance/style-guide/technical-content-a-to-z https://www.gov.uk/guidance/style-guide/technical-content-a-... also looks useful
- ndespres 1y agoThere’s so much value in consistent, expertly-written technical documentation that outsourcing it to the hallucination machine is a pointless exercise in aggravation. I do not wish to read machine-mangled slop. I want an expert to write expertly.
- AdmiralAsshat 1y agoMost of this looks quite good! 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.
- k__ 1y agoYeah, I was thinking the same. They got lost in the details.
- unethical_ban 1y agoI understand having both, particularly in an industry with many non-English native speakers. 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.
- AdmiralAsshat 1y agoI would even be okay with maybe including some "common" mistakes in the style guide if they are particularly prone in your field/organization--those are useful for even native speakers sometimes that confuse there/their/they're, etc. [0] 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-grammar-mistakes/ https://www.oxfordinternationalenglish.com/common-english-gr...
- 1y ago
- _9ptr 1y agoSection 4.6 is certainly ridiculous, but I suppose you can just ignore it.
- jacobgkau 1y ago> Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test", 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-universally-applicable-alternative-to-sanity-check https://english.stackexchange.com/questions/282282/near-univ...
- perching_aix 1y agoI usually use "smoke check/test" or "smell test", but if you have a specific context in mind, maybe I can give you a different alternative phrase I use or two. Definitely not something I'd force onto others either though.
- wmeredith 1y agoAre we just disregarding the differently-abled people who have a diminished sense of smell? /s
- josefx 1y ago> "smell test" There are a lot more people who would fail that test and be offended when pointed out. That group includes some forms of mental illness as well.
- perching_aix 1y agoDon't people who "fail a smell test" and get offended do so because they they think it's a propestourous claim they're failing it? It's kind of the opposite situation, cause wouldn't that make them not take it on themselves by default and thus not wish for the nonuse of this phrasing?
- perching_aix 1y agoMight 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".
- BalinKing 1y agoIt might be dialectical, but in American English, I think “reference material” sounds fine. (Maybe “material” in this context is uncountable or collective or something)
- Chilko 1y agoThat 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?
- Hendrikto 1y agoNotably, because German has more articles and conjugations, this writing style is very clear and easy to follow in German, at least to native speakers.
- oasisbob 1y agoIt'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.
- markedathome 1y agoAre there any comparisons between this and other style guides from the likes of IBM, DEC, Sun, Apple (Early MacOS), Microsoft, etc? All of these had in-house printshops, so would have had some style guides even if just to provide consistency for internal use.
- dctoedt 1y agoParts 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.
- Scubabear68 1y agoIn my experience, technical people tend to tag way too many topics with “simply”. It is usually best to get rid of the word.
- dctoedt 1y agoFair.
- IshKebab 1y agoI agree. It usually seems simple to the author but it's bloody annoying when some documentations says something is simple and it actually isn't.
- dctoedt 1y agoFair. Context matters.
- ar_lan 1y agoI refuse to use the word "simple" in my docs writing for this precise reason. I have come to view the word to seem condescending/elitist, even if that's not the intent. If something is written as simple, but I as an entrant to something view it as not simple, I'm going to be severely discouraged - "if this is the simple thing, what is the hard thing?" It's often an unnecessary adjective.
- jonathanlydall 1y agoI think good technical writing is a lot like good interior design. 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.
- throwaway328 1y agoMaybe that's a good recipe for reliable technical documents, but arguably not great ones. Some of my favourites writers - Donald Knuth, Leo Brodie, Marshall Kirk McKusick, Harley Hahn, Jeff Duntemann, Beej, Nils Holm, surely missing more - write with a lot of flair and personality. I mean, it certainly doesn't feel cold and lacking in emotion. Oh, Dennis Yurichev too.
- patcon 1y agoA friend who ran a mildly popular dev tool (4k+ stars) kept really stellar docs, and his process of updating them was to sit down with a bottle of whiskey every few months, and doing a marathon doc-writing session. the brand voice would come from him being a funny human and getting a little tipsy. I suspect his silly and fun-sounding "kinda drunk" brand voice was what set them apart from all the other boring dev tools in the space.
- dandano 1y agoPretty solid - I'll add this to my list that I refer to for writing. I often use the Australian Style Manual [0] and Divio Documentation System [1] as a foundation to technical writing and also user documentation. [0] https://www.stylemanual.gov.au/ https://www.stylemanual.gov.au/ [1] https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/
- Cthulhu_ 1y agoGovernment resources are great, we frequently refer to the UK's design system too for... accessibility-maxxing? https://design-system.service.gov.uk/ https://design-system.service.gov.uk/
- Savageman 1y agoI didn't read the article yet. Does anyone know if it's better than the Google one here? [https://developers.google.com/tech-writing/overview https://developers.google.com/tech-writing/overview]
- PandaRider 1y agoTLDR: which is better? it depends RedHat's style guide is far more detailed and closer to a reference/explanation (i.e. going by Diátaxis definition). Google's technical writing is shorter and closer to tutorial/how-to guide. I recommend the Google's technical writing if you're a coder or a beginner. RedHat is for folks who already know they need this on first look.
- Savageman 1y agoOk I phrased it badly with "better", I wanted to know how they compare. Your answer is perfect, thank you!
- userbinator 1y ago[dead]
- boston_clone 1y ago“They” has been used as a singular pronoun for hundreds of years.
- boston_clone 1y agofor the haters: https://www.merriam-webster.com/wordplay/singular-nonbinary-they https://www.merriam-webster.com/wordplay/singular-nonbinary-...
- hliyan 1y agoParticularly satisfying to see this section calling out a lot of business jargon: https://stylepedia.net/style/#avoiding-confusing-language https://stylepedia.net/style/#avoiding-confusing-language e.g. best-of-breed Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, and optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims. bleeding edge Do not use. boil the ocean Do not use. State exactly what you mean, such as "increase the scope hugely".
- froobius 1y agoFunny thing is that to people who use those terms regularly, they are "stating exactly what they mean". I.e. "increase the scope hugely", the word "scope" itself comes from greek with its core meaning revolving around "viewing" or "looking". It's only because we are all familiar with it also meaning the scale / amount of things a project should cover, that we all understand. (I guess there's a metaphor of the project "looking over" more as the number / magnitude of goals increases.) So it shouldn't be "state exactly what you mean", because they are. It should be more like: "state what you mean using widely used language if possible"
- Cthulhu_ 1y agoIt makes sense too when you fully understand your audience isn't exclusively English; expressions will be more difficult to read for ESL, and difficult if not impossible to translate to a non-English language. And the docs site is available in 8 different languages. With translation tools (from the past... 3 decades, starting with Babelfish) and modern-day documentation processing / retrieval tools (LLMs), simplicity, clarity and consistency are even more important. But it's timeless advice.
- jack1243star 1y agoThe example sentence "Red Hat releases no upgrade before its time." Should perhaps be "it's".
- zufallsheld 1y agoNo, see https://www.merriam-webster.com/dictionary/ahead%20of%20one's/its%20time https://www.merriam-webster.com/dictionary/ahead%20of%20one'...
- Cthulhu_ 1y agoIt's not short for "it is" in this context, more like "of it", as in, "the time to update it"
- phendrenad2 1y agoDoes this conflict with the IBM Technical Style Guide? https://www.google.com/books/edition/The_IBM_Style_Guide/77WoO_P8yA4C?hl=en https://www.google.com/books/edition/The_IBM_Style_Guide/77W...
- latexr 1y ago> Do not use an apostrophe to denote a plural. Bit weird that correct use of the language is part of a style guide. Perhaps this particular mistake happens often enough they felt the need to codify it?
- dghf 1y agoFrom 2.5. Using Who, Whom, That, and Which Correctly: > This book belongs to whomever purchased it last week. That should be "to whoever", surely? The pronoun is acting as the subject of the verb "purchased".
- greggyb 1y agoYet "whomever" is also the object of the preposition, "to". Certainly, if we took the primary clause of the sentence and substite in any number of pronouns, you'd agree that the objective forms are correct: The book belongs to whomever. Not "whoever". The book belongs to her. Not "she". The book belongs to us. Not "we". I don't know the English grammatical rule for this situation, but it certainly seems reasonable to say that the dependent clause does not get to dictate the form of an independent clause.
- dghf 1y agoBut on the other hand: "The book belongs to the person who purchased it last week". Not "whom". I think it is reasonable to say that the object of the to is not "who(m)ever", but the entire clause "who(m)ever purchased it last week"; and that clause should follow normal subject/verb agreement. Similarly: * "I don't know who purchased the book last week", not "I don't know whom purchased the book last week." * "This is the person who you said purchased the book last week", not "This is the person whom you said purchased the book last week." I've done some digging, and Fowler, Partridge and Gowers all support my stance, so I'm fairly confident in it now.
- Hendrikto 1y agoIrrelevant. The original example given is in the dative case, so it has to be “whom”. It’s really as simple as that.
- dghf 1y agoNot irrelevant at all. The case of the relative pronoun is determined by its role in the relative clause, not by the role of the relative clause in the sentence as a whole. See: - H. W. Fowler, A Dictionary of Modern English Usage - Eric Partridge, Usage and Abusage - Ernest Gowers, The Complete Plain Words who are unanimous on this point.
- azangru 1y agoWhy do they have this in the list of examples of 'run-on sentences': > Bad: To access your programs click the Start button. > Improvement: To access your programs, click Start. Sure, the improved version has added a comma, but the initial version is not a 'run-on sentence'; it does not contain 'two or more complete ideas that are joined without punctuation'. The comma here is completely intonational; it would not be needed if the word order was different, as in 'Click Start to access your programs'.
- jasoneckert 1y agoI'm somewhat disappointed that the 'Copyright © 2025 Red Hat, Inc.' line at the top didn't read 'Copyleft 2025 Red Hat, Inc.'
- oasisbob 1y agoI find it interesting that the changelog for the doc refers to removing guidance for the use of em dashes in 2024. I tried tracing the history back in Github, and it seems that the intent was to prohibit the use of em dashes in normal prose: > In technical content, use a dash to show a range. Otherwise, use a colon or other suitable punctuation. Do not use em dashes. https://github.com/StyleGuides/WritingStyleGuide/pull/618 https://github.com/StyleGuides/WritingStyleGuide/pull/618 Anyone know why this was removed? It matches my training as a public-school student in the US, including in college while working on my Bsc in the natural sciences.
- ghaff 1y agoI was on Red Hat’s informal style committee (Word Nerds) which wasn’t specifically technical writing though we had technical writers on it. A lot was fairly detailed oriented stuff but we also covered more general topics.