Hacker News new | ask | show | jobs
by jaredcnance 1952 days ago
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.

1 comments

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]