Writing in style

Posted on 2024-08-14

As I mentioned in a previous post[1], I'm struggling at the moment with complexity of markup in our developer documentation at work. It seems to me that we keep coming up with new requirements for formatting content that aren't ultimately making anything easier to read.

1 - Technical writing is too complex

Following a discussion I had with a programmer friend yesterday, I decided to spend some of my time today going through some of our issues and coming up with a plan to tackle them. The biggest issues I could see were as follows:

• We use too many tables for structured technical information such as parameter names/definitions.
• We use too many callouts and we use them inconsistently, meaning they risk losing meaning.
• We're inconsistent with how we describe requirements.

To address these issues, I've started writing up a new style guide for our technical writing team. For the most part, we still adhere to the Microsoft Style Guide for our general writing style, but I've added the following caveats:

• We MUST make use of IETF RFC 2119 key words[2] in prose to make the necessity of an action/step clear.
• We SHOULD use callouts as sparingly as possible, and MUST follow a strict set of rules dictating when it is appropriate to use them.
• We MUST write all parameter/argument/property descriptions as Description lists[3] rather than tables or bullet lists.

2 - IETF RFC 2119 (gemini)

2 - IETF RFC 2119 (https)

3 - Description Lists (MDN)

After some tweaking to get description lists working with our translation platform, I think I'm ready to start going through some of these documents to clean them up. I'd like to drastically reduce the number of React components being loaded on a page at any one time, and try and make as much content readable in plain text as possible.

✉️ Tell me what you think