Report drafting
A technical report must let a reader with general technical knowledge, but no knowledge of the project, understand exactly what the author meant without being able to ask. Every rule below follows from that. Three things must be clear in every section:
- the technical statement itself (facts, data, conclusions),
- what was already known and what is new,
- what the author did personally.
Method follows H. Hering, How to Write Technical and Scientific Reports (3rd ed., Springer 2025), Ch. 3.
Before writing
- Rules first. Check for a template, house style, journal guidelines or a style sheet (
style-sheet.adoc, seereport-outline). Their conventions override the defaults here. - Work from the outline. If there is an outline or content map, draft against it. If there is none and the section is longer than a page, sketch its subsections first (or decide consciously that none are needed). For a whole report with no outline, use
report-outlinefirst. - Know the reader. Who reads this section, what do they already know, what will they do with it? Experts on a project routinely overestimate what readers know.
Never invent
Do not invent measurements, results, citations, part numbers, instrument data or sources. When information is missing, mark the gap so the author can search for it:
// ###Un: maximum deviation of the old sensor? (needed for the comparison)
The new sensor deviates from linearity by at most 3 %, the old one by at most +###+ %.
% ###Un: maximum deviation of the old sensor? (needed for the comparison)
The new sensor deviates from linearity by at most \qty{3}{\percent}, the old one by at most \#\#\#~\%.
- Comment markers:
###Un(unknown fact or value),###Lit(citation or bibliographic data missing),###iS(introductory or connecting sentence still needed),###Fig/###Tab(planned figure or table). - A visible gap inside a sentence is written
+###+in AsciiDoc (a bare###is highlight markup there) and\#\#\#in LaTeX (a bare#is an error). - Mark only what blocks the text: a value a sentence needs, a claim that needs a source, a decision that changes the content. Collect secondary missing details (inventory numbers, firmware versions, settings) in one
###Uncomment block per section, or as empty cells in an equipment table, instead of dozens of inline gaps; a chapter riddled with markers is hard to read and to finish. - An unconfirmed fact that the text relies on (a configuration "to be checked", an assumed value) must be visibly marked in the rendered text too ("4s3p (to be confirmed)"), not only in a comment; otherwise the draft states a guess as fact.
- Do not write a conclusion that depends on a missing value ("this meets the required accuracy of +###+ %"). Phrase it conditionally ("this meets a requirement of up to x % of span") or leave the conclusion as a marked gap.
- Tell the user which gaps you left, grouped by what they need to look up.
How to write each part
Read references/sections.md for the recipe of the part you are drafting: abstract, introduction, state of the art, methods/test setup (with the reproducibility list), results, discussion, summary/conclusions, appendices, front matter. The essentials:
- Introduction and summary are read first and by almost everyone. Write them with the most care. The introduction gives the starting situation, relevance, task/goal and the route through the report. The summary says what was asked, what was achieved, where the difficulties were, what was not done and why, and recaps the chapters in order.
- Guide with words. Every chapter and section opens with a sentence that says what comes and why, and ends (where useful) with a sentence that says what it means or leads to the next part. A heading is never followed directly by a figure, table, list or citation.
- The heading is not part of the text. The first sentence must make sense without the heading ("The measuring devices were calibrated with …", not "…was done with …").
- One name per thing. The same part, process or quantity always gets the same term; synonyms make readers think a different thing is meant. Name parts by their function ("retaining plate", "input gear", "carrying frame"), not generically ("plate", "gear", "the design", "variant 1"). With an assembly drawing, add the position number at first mention: "cover plate (23)".
- Numbers instead of adjectives. "much more linear" becomes "max. 3 % deviation instead of 7.6 %". If the number does not matter, drop the adjective.
- Plain sentences. At most about 25–30 words, one new fact per sentence, at most six sentences per paragraph, subject and verb early, explicit connectives ("therefore", "because", "if … then").
report-copyedithas the full rule set; follow it while drafting so the copyedit pass stays light. - Voice. Follow the venue. Traditional engineering reports are impersonal (passive, "we" only for the team in the summary); most journals now prefer active voice and "we". Either way, the actor must be unambiguous: "by the operator" vs "by the controller".
- Tense. Present tense for facts and for what the report shows; past tense for what was done in the experiments.
- Cite as you write: every statement, value, figure or table taken from elsewhere gets its citation now, not later. See
references/citations.md. - Reproducibility. Methods and test sections must let someone repeat the work and get the same result (equipment, settings, specimens, instruments, formulas with sources). See
references/sections.md. - Overview in figures, detail in text. Plan for each important statement whether it is shown, written, or both. Make figures and tables while writing the text, not at the end; late figures look rushed.
Figures, diagrams and charts
Read references/figures.md before creating or revising any figure, PlantUML diagram or chart. Core rules:
- Caption below the figure; it says what is shown, where, and under which conditions ("Pressure measuring points P in the cooling channel of the die-casting mould", not "Measuring points"). Borrowed figures carry the source in the caption.
- Every figure gets an anchor ID and at least one cross-reference in the text, placed before or next to it, and the text says what the reader should see in it.
- Didactic reduction: show only what supports the statement, at most about 4–7 main elements; one visual encoding (arrow style, colour) = one meaning, explained in a legend.
- Chart axes carry quantity and unit ("Force in N" or "Force / N", never "Force [N]"), values increase up and to the right, time runs left to right, linear scales include zero, and nothing is stretched to exaggerate.
- Readable when printed in greyscale and for colour-blind readers: never rely on colour alone.
Tables
Read references/tables.md for tables, evaluation (weighted scoring) tables and morphological boxes. Core rules: caption above the table; header row and first column understandable without the text; units in the header, not in every cell; every table referenced in the text; large number tables go to the appendix with a chart in the text. In evaluation tables, all points are benefit points from the user's perspective (more cost or weight gets fewer points), every table has its own legend, and the winner is stated explicitly.
Formulas, units and computations
Read references/formulas-units.md for equations, computations and notation. Core rules: symbols italic, units upright, a space between number and unit (5 mm, 20 °C), every symbol explained right before or after the formula or in a legend below it; computations go formula → substituted values → result → selection statement ("selected: bearing 6305, C = 25 kN > C_req = 23.8 kN").
Markup: AsciiDoc or LaTeX
Write in the markup the report already uses, and keep the project's conventions (class, preamble, macros, one sentence per line) unless asked otherwise.
- AsciiDoc:
references/asciidoc.mdhas the patterns for captions, IDs, cross-references, PlantUML blocks, stem equations, bibliographies, footnotes, admonitions and includes. Use<<id>>cross-references and explicit IDs ([#fig-…],[#tab-…],[#eq-…],[#sec-…]). - LaTeX:
references/latex.mdhas the patterns for figures, tables (booktabs, siunitx columns), equations, siunitx units, biblatex citations, cleveref references, glossaries, PlantUML and pgfplots. In floats the order is graphic →\caption→\labelfor figures and\caption→\label→ tabular for tables; units always through siunitx (\qty{5}{\milli\metre}); references through\cref(orFigure~\ref).
Never hard-code numbers such as "Figure 3" or "Sect. 2.1"; let the markup generate them.
After drafting a section
Check before handing it over:
- Opening sentence under every heading; nothing (figure, table, list, citation) directly after a heading
- Every figure/table: caption in the right place, ID, referenced and interpreted in the text, source if borrowed
- Every borrowed statement, value, figure and table cited; every citation resolvable
- Terms match the style sheet / earlier chapters; abbreviations defined at first use
- No vague comparatives where a number exists; no invented facts; gaps marked with
### - Numbers and units in the right notation; symbols explained
- Section delivers what the outline's content map promised
If the report-review skill is installed alongside this one, its linter (../report-review/scripts/lint_report.py <master.adoc|main.tex>, relative to this skill's directory) checks captions and their position, labels/IDs, cross-references, citations, lone subsections and number–unit spacing mechanically, for AsciiDoc and LaTeX.
Finish by telling the user what you drafted, which ### gaps remain, and any assumption you made about voice, terminology or notation.