Rubric for Technical Writing

A piece of technical writing should be:

• Directed. Whenever you write, you need to know your target reader, and direct your writing to them. Take into account their expertise and background knowledge, and adopt a tone that's appropriate for the relationship you have with them.
• Consistent. Be consistent in tone and style. Don't be playful and chatty and then suddenly turn serious and abrupt.
• Professional. Avoid slang, and if you want a global audience, beware of cultural references they might not be familiar with.
• Informative. Try to explain everything that your reader needs to know. Be as explicit as possible, and don't make your reader join the dots or fill in gaps. If there's a conclusion you want them to draw, lay it out.
• Precise. Use the right words and say exactly what you mean, and remember that anything that can be misunderstood probably will be.
• Self-contained. If your explanation relies on understanding something that appears somewhere else, consider including at least a summary of it so that your reader has everything they need in front of them.
• Clear and simple. Achieving clarity and simplicity takes a lot of work but pays off. Keep reworking your writing, reading it aloud to yourself and trying to spot places that aren't completely clear.
• Concise. Use short words rather than long words, avoid saying the same thing twice, and ruthlessly eliminate any parts that are unnecessary to your argument.
• Easy to read. Unlike a good novel, a technical article is rarely savored. Make it easier for your reader to extract the key points by giving your argument a clear structure, reflected in its visual appearance. Use structuring devices like subheadings and bulleted lists, but don't go crazy. Don't nest things too deeply, and keep sentences short. Find pithy phrases to use as titles for sections and subsections, and consider titling paragraphs and list items as well (bolding the titles so they stand out).
• Accessible. Don't just explain ideas in the abstract; include concrete examples whenever possible. Make it clear where an example begins and ends. Use diagrams when explaining structures and relationships that are more easily grasped visually.

Common pitfalls:

• LLM slop. LLMs can be very helpful for reviewing writing and suggesting ways to tweak a sentence or reformulate an idea. But if you cede your writing entirely to an LLM, you'll probably end up with slop: verbose and clunky text that doesn't say very much, formulaic phrasing ("it's not merely an X, but it's a Y"), marketing fluff ("seamless transitions"), and worse.
• Avoiding the hard stuff. It's tempting to write down what you understand and skip what you don't. But consider that the bit you don't understand might be exactly what your reader needs to know, so you'd do well to figure it out and explain it.
• Quantity over quality. More is not better. Don't pad your writing to make it look like you did more work.

Competency levels:

• Deficient. The writing is poorly structured, hard to follow, and it's not even clear what it's trying to say.
• Emergent. The piece is structured and comprehensible, and includes some reasonable points but doesn't fit together into a coherent whole.
• Competent. The piece succeeds in conveying its argument, and has most of the qualities listed above. But it's not a pleasure to read. Perhaps it's more verbose than it needs to be; or it explains in text what could be conveyed much more quickly in a diagram; or it feels a bit flat and boring because it lacks energy and charisma.
• Expert. The writing is engaging from start to end, and draws the reader along. The examples are compelling and maybe even entertaining. Explanations of familiar ideas are so appealing they make the reader want to reuse them. Even though the topic is technical, you get a sense of the writer's personality, and their passion comes across.