News for hackers. Stuff that matters.
Re:The Grand Unified Theory of Documentation by npunt on Friday April 16, 2021 @01:02AM (#26829688)
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.

Re:The Grand Unified Theory of Documentation by eru on Friday April 16, 2021 @01:09AM (#26829742)
About 8: this habit might make your docs sound a bit monotonous, but it also helps with 'grepping' through them.
Re:The Grand Unified Theory of Documentation by vicda on Friday April 16, 2021 @03:35AM (#26830742)
We don't read documentation to entertained, but to solve problems. How searchable your text is extremely important.
Re:The Grand Unified Theory of Documentation by neetrain on Friday April 16, 2021 @01:18AM (#26829804)
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.
Re:The Grand Unified Theory of Documentation by eru on Friday April 16, 2021 @01:27AM (#26829864)
Yes, literature and technical documents have different requirements.
Re:The Grand Unified Theory of Documentation by bobthepanda on Friday April 16, 2021 @11:58AM (#26835533)
At least in the US my undergrad computer science degree had a course on specifically writing technical documentation