Notes on Technical Writing
A lot of technical writers focus on the style of the text. For example, I&#x27;ve seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization.<p>I wish tech writers would channel their focus elsewhere:<p>- If you haven&#x27;t got it working, don&#x27;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.<p>- Show fully qualified imports in code samples. If you don&#x27;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.<p>- Create automated testsuide for your code samples.<p>- Mandate that lack of docs be a blocker for a release.<p>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 &quot;obvious&quot; parts of the code to get it to work, that&#x27;s when I get really frustrated.<p>The article seems to be deeply focused on the style. I can&#x27;t remember when I got frustrated with documentation because the style was bad, or because the sentences were too long.