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.
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.