Get to the point
When writing docs, you should go straight to the point – you can start with it, it can even be your title. From there you can provide context, explain the thought process and talk about potential alternatives.
You should do so for two reasons:
- People’s attention span is short and more importantly they have limited time. Give them the opportunity to skip the context/rationale if they are aware of the issue and agree with your opinion
- It is much easier for readers to follow your train of thoughts if they know what the final destination is
At a higher level, keep your doc crisp and simple. Writing a doc as a software engineer is fundamentally different than writing a research paper. Start a paragraph with a clear point and don’t use every possible trick to make your doc/work/opinion complex when it isn’t, e.g.:
- Don’t use exotic words – don’t write utilize when you mean use
- Remove fluffy/meaningless syntax – you can write “I think” (or better not write it) rather than “After pondering about it for days, the opinion I ended with is”
Interestingly enough, I can reasonably guess the level of an engineer based on how their doc is written. It’s a very strong signal as docs reflect both their communication skills and how clear and well structured their thoughts are.
What tips do you have for writing? I have a few more coming up :)