Agree to all! When I was rewriting the OneSignal docs I followed the same rules you laid out as well as a few more:
5. Get every step right. Don't make assumptions that the reader knows how to configure something you mention in passing, spell it out. This is especially important if good engineers are writing docs since they leap over little things that less skilled users might not know.
6. Write for translators. Many users don't speak English well and will be running docs through Google Translate. This is a variant of your #1.
7. Consider docs a seamless extension of the product. Use the exact wording and same visual language of the product and make sure docs pick up from where exactly the user was in the product. Evaluate these flows so wherever someone gets tripped up, the right doc is there waiting. Ideally do bidirectional linking so the product itself also links to these.
8. Super consistent language. Figure out your nouns and verbs: someone playing a game is always a 'player' (vs sometimes a 'user' or 'gamer'), someone sending a file is always 'transferring' (vs sometimes 'sending' or 'uploading'), etc. Unless you pay close attention ambiguity is going to creep into documentation.
I don't know whether it is only in my country, but teachers in school teach students otherwise.
Not repeating the same word for the same things is alright for elegant literature, but problematic in the digital era.
Comments
Agree to all! When I was rewriting the OneSignal docs I followed the same rules you laid out as well as a few more:
5. Get every step right. Don't make assumptions that the reader knows how to configure something you mention in passing, spell it out. This is especially important if good engineers are writing docs since they leap over little things that less skilled users might not know.
6. Write for translators. Many users don't speak English well and will be running docs through Google Translate. This is a variant of your #1.
7. Consider docs a seamless extension of the product. Use the exact wording and same visual language of the product and make sure docs pick up from where exactly the user was in the product. Evaluate these flows so wherever someone gets tripped up, the right doc is there waiting. Ideally do bidirectional linking so the product itself also links to these.
8. Super consistent language. Figure out your nouns and verbs: someone playing a game is always a 'player' (vs sometimes a 'user' or 'gamer'), someone sending a file is always 'transferring' (vs sometimes 'sending' or 'uploading'), etc. Unless you pay close attention ambiguity is going to creep into documentation.
About 8: this habit might make your docs sound a bit monotonous, but it also helps with 'grepping' through them.
We don't read documentation to entertained, but to solve problems. How searchable your text is extremely important.
I don't know whether it is only in my country, but teachers in school teach students otherwise. Not repeating the same word for the same things is alright for elegant literature, but problematic in the digital era.
Yes, literature and technical documents have different requirements.
At least in the US my undergrad computer science degree had a course on specifically writing technical documentation