Notes on Technical Writing
A lot of technical writers focus on the style of the text. For example, I've seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization.I wish tech writers would channel their focus elsewhere:- If you haven't got it working, don't document it. Getting information by talking to SWEs is not enough. Your docs will lack depth and preciseness, and it will show. A lot.- Show fully qualified imports in code samples. If you don't know what that is, ask SWEs. Given a computer with installed dependencies (such as Maven, Pip, npm, etc.), even your (grand)mother should be able to follow the docs.- Create automated testsuide for your code samples.- Mandate that lack of docs be a blocker for a release.When there are docs written in perfect style and English, yet none of the code samples works, or when I have to spend 30 minutes finishing the "obvious" parts of the code to get it to work, that's when I get really frustrated.The article seems to be deeply focused on the style. I can't remember when I got frustrated with documentation because the style was bad, or because the sentences were too long.