The IBM style guide

What Hacker News says

1. chaoticmassAug 2018
   While there are many excellent style guides out there, I personally went with the IBM Style Guide: Conventions for Writers and Editors [0] when I started writing technical manuals and documentation.

   It is so comprehensive that the book ends up describing itself exactly, as if it were some kind of meta manual.

   [0]: https://www.amazon.com/IBM-Style-Guide-Conventions-Writers/d...

   thread
2. ddriMar 2017
   Interesting to see this posted, as this wasn't particularly widely used even at Red Hat. And the timestamps for revision history show you that it's of a certain era.

   What I would recommend is something like the MailChimp style guide: http://styleguide.mailchimp.com/

   The upside here is that those teams are small and centralised and obsessive over the tone of their product. The same goes for other SaaS companies like Intercom (Elizabeth is an amazing content strategist). They have to be.

   For context, I'm an alumni of the Red Hat content team, which I joined from a corporate background and was frustrated to see the team relied on the IBM Style Guide. I pushed for Red Hat to make a canonical open source style guide, as I researched common patterns across engineering and tech writing that can create disparity in UIs or APIs if one group ends up writing one way, and another the other.

   For various reasons this wasn't a feasible project so my team focused on tooling instead (creating the PressGang CCMS internally, and then I took funding from one of the Red Hat founders to launch Corilla, a collaborative publishing tool for technical writers considered "the GitHub for content teams").

   This style guide here is at best a reference for the kinds of things you might want to consider if you're building one for open source. In my era this guide was pretty useless though, as the content team voted for a strange hierarchy of style guides going from the IBM, then the CMoS, then the American Heritage dictionary, and then this guide. Or maybe some variation - nobody paid attention and we all just used the IBM and had opinions.

   This is why the smaller SaaS companies make the best style guides (and the MailChimp one is not only creative commons so you can use it too, but not stuck in the awful DocBook XML format!).

   Show morethread