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.
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.
Good point! It has been years since I last published a PDF on the web (HTML has my heart :D) -- this is helpful information to have! I can set up a redirect to a more descriptive URL.
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.
When I read documentation, I love when there are a few snippets I can read, copy-paste, and adapt to work with my code, particularly when a library is vast. Google does a good job of this, for example. In some of the cloud code snippets, you can copy-paste and they _just work_ (after you have authenticated).
> e.g. without imports, so you can't just run it as is.
I think it only makes sense to omit imports when a guide is walking through a single file (i.e. step-by-step), or future code snippets are a continuation of existing code. I also love it when guides specifically call out what package(s) I need to install.
I spent time over the holidays working on edits, document order, formatting, etc., but I did not consider that "this post" was confusing since everything would be concatenated into a book. This is excellent feedback. I appreciate it!
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