This is the evolving set of recommendations I share with my graduate students for technical writing...
-
Empathy: This is the single most important principle of technical writing. Try reading what you write from the perspective of somebody who has not spent the last few months working on your problem. Better yet, find such a person and see if they understand everything you are talking about. Don’t just take their word for it, ask them to tell you what they understand in their own words. See where they struggle and debug your paper: Do they get lost in too much detail and miss the main point? Do they get disoriented because you jump around too much? Are there terms they do not understand? Fix the paper using the following techniques until a dedicated freshman can understand all the important points.
-
Winston’s Onion Rule: The document should state the most important points first, and expand on them gradually. It is a mistake to keep any important points until the end of the paper. Only details and supporting material should be left to the end. If I stop reading the document at any point, everything I haven't read so far should be less important than everything I have read up to this point:
-
The title should be descriptive of the main point.
-
The first sentence should state the main point.
-
The first paragraph should expand on the first sentence.
-
The first section should expand on the first paragraph.
-
The first chapter should expand on the first section.
-
The whole paper/thesis should expand on the first chapter, etc.
-
Yuret’s Fractal Rule: Parts at every level of your document, down to each paragraph, should have their own introduction / conclusion to keep the reader oriented (i.e. stop them from asking “What is this person talking about now, and why?”):
-
The first chapter of a paper/thesis should state the topic of the paper/thesis and the last chapter should summarize its point.
-
The first section of a chapter should state the topic of the chapter and the last section should summarize its point.
-
The first paragraph of a section should state the topic of the section and the last paragraph should summarize its point.
-
The first sentence of a paragraph should state the topic of the paragraph and the last sentence should summarize its point.
-
No undefined terms: Any technical term your nine year old niece would not understand should be defined before first use. Any acronym should first be given in parentheses next to its long form before first use. All variables in equations, all axes in graphs should be explained at the first opportunity. Tables and Figures should have descriptive captions that can be understood stand-alone. Technical terms and mathematical notation should be used consistently, no confusing variations allowed (i.e. calling the same thing context vector somewhere and word context vector elsewhere will confuse the reader into thinking these are two separate things).
-
Replicability: Science is based on replicable results. Your paper should provide enough detail (possibly in the appendices), and links to its code and data, to replicate each of its results. In particular, for each set of experiments you should have:
-
Data table: e.g. in a natural language processing experiment, things like number of words and sentences in train, dev, test; vocabulary size, tagset size, tag frequencies, out-of-vocabulary rate, average sentence length, i.e. any data statistic relevant to the task should go to a data table.
-
Parameter table: things like the model structure, the training algorithm used, the hyperparameters used, number of training epochs, and any other details related to experimental replication should go to a table.
-
Result table: the results (table or plot) should clearly indicate the evaluation metric, sensible lower bound baselines, upper bounds (e.g. inter-annotator agreement) if available, and current state of the art in published work to put your results in perspective.
- from: http://www.denizyuret.com/2016/03/how-to-write-technical-paper.html