Basic principles of technical writing
Following are some basic principles in technical writing.
- Definition of terminology:
Every technical term must be defined before you can use it.
If it is defined in established work, such work must be cited.
- Treat the whole paper like a proof:
Every statement must be supported, either by the premises that you have established earlier, or by some established work (like axioms in a proof).
If it is supported by established work, such work must be cited.
- Don't assume the readers see what you see:
For every figure, table or graph, the caption should provide readers with sufficient information to understand it.
In the text, try to make precise references to the figure, table or graph.
E.g. "Algorithm M produces a result of 23.44 (row 2, column 4).
This supports the claim that ...."
- Keep it simple:
Try to say one point at a time.
Make sure that the readers know where you want them to pay attention to.
- Avoid long sentences: (see example)
While long sentences do not necessarily make bad writing, they are very good at concealing confused ideas.
You want your paper to be as rigorous as a proof (Point 2 above).
In a proof, you want to be able to debate on each single point. For this purpose, short sentences help.
- Say no more than needed.
- State facts before making claims (in different sentences if possible):
A normal paper in experimental science should contain a lot of factual description of what you have done,
what experiments you have conducted and what the results are.
Only after these are described should you make analysis and claims
(based on the results).
- Elaborate or remove:
We often encounter situations where a simple sentence is not sufficient to explain a point.
In such situations, you have to decide whether to elaborate or to remove the point.
All sentences left in the document must be comprehensible.
- Dangerous words to use:
Ask yourself whether you can justify yourself every time you use words like "best", "optimal", "maximize", etc.
- Bibliography: Citations must be complete.
Many formats are acceptable, but you must be consistent.
Basically, you need to include the authors' names, title of the article or book, publisher for books,
name of the journal or conference for papers, dates of
publication and page numbers for articles.
Checklist for technical papers (most of these points surround your claims)
- Are the objectives and scope clear? In other words, what is the paper about?
- Have you made it clear what you have done?
(No matter how good your work is, it won't be appreciated unless it is clear.)
- Are the claims clearly stated?
(The onus is on you to make this clear. The referees should not be expected to draw their own conclusions.)
- Are the claims significant? do they fully reflect what you have achieved?
(If the claims are trivial, the paper will most likely be rejected.)
- Are the claims substantiated?
- Did you make it clear where in the paper each claim is substantiated?
Basic technical writing Example
The above advice is given by
Edward Tsang; last updated 2015.01.07