20 Tips for Technical Writing
From Coursera course
If you are working in the software field then you will come to a point where you will need to write some documentation. This guide will help you to hone those technical writing skills:
Use acronym properly
Avoid using `this`, `that`; keep sentences in active voice
Active voice sentences are shorter
Reduce there is/there are
Be professional in writing
Convert long sentences to lists
End an introductory sentence with a colon instead of a period
Keep paragraphs to the point and short
Identify your target audience and adjust the level of document
State documents scope and what is not under the scope
Break your topic into sections, add an index
A period separates distinct thoughts; a semicolon unites highly related thoughts
Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant.
Review with peer
Do an outline exercise
Add simple self-explanatory images, or add callouts in the image
When adding sample code make sure it is running and follows all coding standards
To ease the sample coding experience add example as well as anti-examples
If peers are experienced then add comments for why instead of what is code doing!
Write more and try to use Grammarly to improve.