BOboomskats·Jan 4, 2024
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
Read the rest
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