Writing is communication. And in tech field, it is one of the crucial skills to master. If you want to share your ideas to wider audience, you need to write blogs, write proposals for conferences, and publish technical papers.
There are two fundamental questions that needs to be asked, before you start writing:
- Who your audience will be
- What you wish to communicate
Other things (like structure and content) generally follow these decisions.
Know your audience
Technical writing is in some sense similar to software engineering, just like you need to understand the who the users for your product will be, you need to know your audience will be.
Most of the times the audience is our future selves. Where documentation written today serves as a point of reference in future.
It's always better to state the assumptions made before hand. And not place any assumption on reader's prior knowledge.
Online Documentation
Most of the stuff we write is meant to be read online in a web browser. There are certain tendencies in web readers, they generally tend to:
- skim through the content
- extract the important parts
- ignore the rest
In such cases, you should jump to heart of matter quickly. Keep the sentences short. And use lots of smaller paragraphs rather than a lengthy blocks, generally it doesn't put a lot of cognitive load on the reader.
Resist the temptation to use illustrations, they should be used as supplements rather than for information. If you are struggling to explain the concept in simpler understandable terms, maybe you do not understand it properly.
If you find it complex to explain something, follow a similar approach to programming and break it into multiple smaller parts. And try to explain each of them individually.
Some in general tips,
- if you're documenting command invocation, it's good idea to include actual command and it's output rather than fictiously fabricated one.
- if you're writing a FAQ style document, include questions which your reader might want to ask, rather than what you think they might ask.
- for project README, it's good to include:
- Short summary of what the tool does
- Installation steps
- Example invocations with expected output