3 ms·

> Revise it, many times, on separate days. You need to keep coming back to it, reading it with a fresh mind that hasn't thought of what you wrote for at least

> Revise it, many times, on separate days. You need to keep coming back to it, reading it with a fresh mind that hasn't thought of what you wrote for at least half a day, preferably longer. Agree completely. Can you recommend any resources that emphasize this point and provide similar helpful documentation guidelines?

kstenerud 7y ago
I don't know of any resources offhand, but the principles of technical writing are very similar to code writing. The biggest difference is that computers only need to be told once, whereas humans need a few (controlled) repetitions and some examples in order to digest something. - Don't Repeat Yourself: Describe it in one place, and then refer to it elsewhere in the document. - Componentize: Build up smaller concepts and then use those smaller concepts to build up bigger concepts, etc. Then you can continue to use simple language with the bigger concepts that are easily broken down because they in turn are described in full. - Each part does one thing and does it well. Don't mix many different concepts in one description. Describe one thing well, and reference it elsewhere. - Keep things short. The longer a section is, the harder it is to absorb. - Naming is important. Use memorable, descriptive names for your concepts. - Have examples that demonstrate your concepts. Don't try to pack many concepts into a single example; that just makes it harder to figure out. - Have a glossary if there are more than 10 new concepts. - Test your documentation on people who are unfamiliar with the project. Ask them where they're getting confused. Confusion is the human manifestation of a bug in your documentation. - Always keep your goal in mind. What should the end result be with your reader? Anything taking longer than 10 minutes is a chore, and only the most dedicated would continue that far. - U/X is important. UI layouts, source code, and documentation all have U/X components to them because a human will be interacting with them / consuming them in some form. Make it easy for them to navigate to what they need.
atoav 7y ago
Another idea is to try on different personas: Put yourself into different roles, e.g. the person who just looks at the examples and skips wall of texts, the person who wants to read up on every nook and crany, the person who has no technical background etc. The cool thing about text is, that it can be many things to many people and this is even more true with hyperlinks. Try to cover all bases at least a little bit and people will ignore the stuff they dislike and go after the stuff they like.
kashyapc 7y ago
FWIW, a couple of books that have helped—and continue to help—me write better: • On Writing Well[1], by the inimitable William Zinsser • Clear and Simple as the Truth[2], by Thomas and Turner I've written some more about the above two books here[3], in a different thread. [1] https://www.goodreads.com/author/show/7881675.William_Zinsser https://www.goodreads.com/author/show/7881675.William_Zinsse... [2] https://press.princeton.edu/titles/9445.html https://press.princeton.edu/titles/9445.html [3] https://news.ycombinator.com/item?id=20062455 https://news.ycombinator.com/item?id=20062455

kstenerud 7y ago

I don't know of any resources offhand, but the principles of technical writing are very similar to code writing. The biggest difference is that computers only need to be told once, whereas humans need a few (controlled) repetitions and some examples in order to digest something. - Don't Repeat Yourself: Describe it in one place, and then refer to it elsewhere in the document. - Componentize: Build up smaller concepts and then use those smaller concepts to build up bigger concepts, etc. Then you can continue to use simple language with the bigger concepts that are easily broken down because they in turn are described in full. - Each part does one thing and does it well. Don't mix many different concepts in one description. Describe one thing well, and reference it elsewhere. - Keep things short. The longer a section is, the harder it is to absorb. - Naming is important. Use memorable, descriptive names for your concepts. - Have examples that demonstrate your concepts. Don't try to pack many concepts into a single example; that just makes it harder to figure out. - Have a glossary if there are more than 10 new concepts. - Test your documentation on people who are unfamiliar with the project. Ask them where they're getting confused. Confusion is the human manifestation of a bug in your documentation. - Always keep your goal in mind. What should the end result be with your reader? Anything taking longer than 10 minutes is a chore, and only the most dedicated would continue that far. - U/X is important. UI layouts, source code, and documentation all have U/X components to them because a human will be interacting with them / consuming them in some form. Make it easy for them to navigate to what they need.

atoav 7y ago

Another idea is to try on different personas: Put yourself into different roles, e.g. the person who just looks at the examples and skips wall of texts, the person who wants to read up on every nook and crany, the person who has no technical background etc. The cool thing about text is, that it can be many things to many people and this is even more true with hyperlinks. Try to cover all bases at least a little bit and people will ignore the stuff they dislike and go after the stuff they like.

kashyapc 7y ago

FWIW, a couple of books that have helped—and continue to help—me write better: • On Writing Well[1], by the inimitable William Zinsser • Clear and Simple as the Truth[2], by Thomas and Turner I've written some more about the above two books here[3], in a different thread. [1] https://www.goodreads.com/author/show/7881675.William_Zinsser https://www.goodreads.com/author/show/7881675.William_Zinsse... [2] https://press.princeton.edu/titles/9445.html https://press.princeton.edu/titles/9445.html [3] https://news.ycombinator.com/item?id=20062455 https://news.ycombinator.com/item?id=20062455