Software Technical Writing: A Guidebook [pdf]

I really like this. It seems very thorough and complete, and most importantly, it really feels like it instills confidence. Excellent work OP, I am absolutely going to give this a read end-to-end.

I've recently come to realise just how much of an effect confidence can have on the productivity of engineers trying to produce technical documentation. I know multiple brilliant, prolific developers who have struggled to put words down, not because they didn't know what to write, but because the perception of increased visibility and permanence of what they were writing made them constantly second-guess their tone, style, sentence structure, grammar, etc.

Speaking from personal experience, Technical Writing Style Guides[0] have been pretty effective at helping overcome that option paralysis, and adopting a style guide [1] helped my team a fair bit. However, by far the biggest benefit came from adding real-time style guide linting to our docwriting devcontainer, via the excellent Vale.sh[2] and the vale-ls[3] language server. It was a total gamechanger.

If you're struggling to find your groove with technical writing, I'd thoroughly recommend trying out this approach (in addition to everything else mentioned in this book). Yeah, I'm sure you could just use ChatGPT to standardise your output to a particular writing style, but if you write code for a living, you'll know there's something about the immediate feedback of a real-time linter that really inspires confidence. And confidence is important.

[0]: https://en.wikipedia.org/wiki/List_of_style_guides#For_the_c... [1]: https://learn.microsoft.com/en-us/style-guide/welcome/ [2]: https://vale.sh/ [3]: https://github.com/errata-ai/vale-ls

The actual blog post announcing this also has an epub! This looks very thorough and an interesting Kindle read.

https://jamesg.blog/2024/01/03/software-technical-writing/

This is a great resource, thanks for collecting them.

A couple points on prospective new writers: while you don't need to be a great (or even good) software designer or programmer or coder to become a technical writer, it truly helps to get comfortable reading and interpreting code. Every minute of an engineer's time that you can save by understanding a feature from its implementation and asking better-informed questions makes you more valuable.

Also, while it's true that there are a lot of tech writing roles in marketing, don't limit to that if you're getting into the field from a different one. Tech writers show up in many contexts, from engineering-focused dev docs to UI/UX design docs to product docs to whitepapers to support knowledge bases. Experience with any of those can lead to more focused technical writing roles later. I've worked the same product documenting role organized under marketing, product, engineering, and support teams, and they all prioritize and value work differently — you might find yourself more compatible with one than the other even if the job req itself is effectively identical.

If I may, you mention one of your duties is to help people find your content. In that spirit, I'd choose a better filename as PDFs generate no preview from meta tags and the link alone is not explanatory when shared.

I've read a few pages and browsed the rest, and it looks very interesting. I appreciate the personal touch and anecdotes.

Also wanted to say that I 100% agree with the "minimum viable code snippets" idea. Too often a manual or a readme shows a snippet e.g. without imports, so you can't just run it as is.

Thank you for sharing!

I'd be interested in some of your insights into how to make a good README.

You only included it under Open Source Documentation, but I believe a good README is mandatory for internal commercial projects as well.

Your effective examples section is great and something I will refer to myself for a while. Thanks!

Nice!

Although, some sections still say “this blog post” and it feels like a bunch of them stuck together with a need for some review maybe?