Re:Ask HN: Which everyday skill is important to master as a ...
by jaredcnance on Saturday February 13, 2021 @01:35AM
(#26121852)
Read. Read a lot. Look for successful documents and emulate their patterns. First, understand what the author was trying to accomplish with the doc, then study the structure of the doc, then dig into the language choices. But, if I had to pick one thing to study, it would be structure. I frequently read tech docs that come off as a stream of consciousness. You have to understand your audience and put the effort in to give them context (the problem, the requirements, the methodology) before giving them the solution.
Also write. Write a lot. And ask for help. If you work with/know someone who is considered a good tech writer, I bet they will help you.
Re:Ask HN: Which everyday skill is important to master as a ...
by jaredcnance on Saturday February 13, 2021 @01:39AM
(#26121864)
Also learn how to diagram and do quick mock-ups. Visuals can help bridge the gap between what you can articulate and what the reader needs to develop a good mental model of the proposal.
[this comment is coming from someone who writes mostly technical design documents needing to communicate a technical solution to a problem while also considering multiple alternatives]
Re:Ask HN: Which everyday skill is important to master as a ...
by bwh2 on Friday February 12, 2021 @11:20AM
(#26115258)
Read the book On Writing Well by William Zinsser.
I completely agree with you but it seems pretty hard to hone that skill if there's no one to give you feedback.
e.g. you write some internal docs but then no one lets you know how could they be more useful/understandable, until someone else comes and re-writes the docs.