Report outline
The outline is the backbone of a technical report. Writing the text is craft; deciding what goes in which "drawer", and in which order, is the creative part, and it decides whether the report has an inner logic a reader can follow. A reader with basic technical knowledge but no knowledge of the project must be able to understand the finished report without asking the author anything. Every step below serves that reader.
Method follows H. Hering, How to Write Technical and Scientific Reports (3rd ed., Springer 2025), Ch. 2.
0. Find the governing rules first
Before proposing anything, find out whether the university, company, customer or journal prescribes a structure, template, page limit, cover/title page, citation style or numbering scheme. Look in the repo (templates, *.adoc skeletons, README, a style guide) and ask the user if nothing turns up. Their rules win over everything in this skill; the defaults here fill the gaps.
1. Analyze the task
Write a short task card (in the conversation or in notes/task.adoc, as the user prefers). Answer from what the user gave you; mark the gaps and ask about the ones that change the outline.
- What exactly is the task, and who set it (supervisor, customer, team, self)?
- What must the report contain? List mandatory content.
- Who reads it, what do they already know, what do they expect? Who decides (grader, customer, reviewer)?
- Why is it written: to document, to decide, to prove, to teach, to be graded?
- Which media and formats (AsciiDoc or LaTeX to HTML/PDF, slides later)?
- Which work steps, help (people, equipment, literature) and deadlines? Which are time-critical?
- Does the task statement already contain a usable title?
Time planning when the user asks for it: estimate realistically, then double it; start writing no later than one third into the project; budget about 1 day for title and outline, about 3 pages of text per day, and 1–2 weeks for corrections, final check and delivery.
2. Title
The same requirements apply to the title, every heading, and every figure and table title:
- contains the main keywords (people find reports through database search)
- short, precise, true; promises nothing the report does not deliver and triggers no wrong associations
- concrete enough to create interest; reads well aloud
- secondary aspects go into a subtitle (
Main title: subtitleorMain title - subtitle)
Method: write down the task, list the keywords, combine them into 5–8 variants, read them aloud, pick one and say why. If a self-coined term or acronym is central to the work, it belongs in the title. Weak patterns to avoid: "Contribution to …", "Investigation of some aspects of …", titles that drop the core topic. A working title is fine early on; settle the final one with the supervisor or customer.
3. Core message, 4-point and 10-point structure
Build the outline top-down so the logic fixed early cannot get lost when sections are later added or split.
- Core message: one sentence stating the main topic, target or result of the report. Insist on one sentence even when it is hard; that difficulty is the point.
- 4-point structure: split the core message into 3–4 main items (e.g. "State of the art - test rig design - test execution - test results").
- 10-point structure: expand into 8–10 chapters. Pick one ordering principle per level and apply it consistently: time sequence, starting conditions, project targets, alternatives, components/assemblies, input to output, direction of force, direction of flow (data, energy, material), improvement steps, related topics.
- Detailed structure: subdivide the large chapters. Before writing a chapter, sketch its subsections or decide consciously that it needs none. The detailed outline keeps growing while the text is written.
- Last check (when the report is done): numbers and wording of the outline/ToC match the headings in the text exactly.
Use the conventional chapter names the target readers expect (a lab report reader looks for "Test setup", "Test procedure", "Results"). For common report types, start from a pattern in references/structure-patterns.md and adapt it rather than inventing from scratch; a pattern lets you skip steps 2–3. If the supervisor publishes a pattern, theirs wins.
4. Rules every outline must pass
Check these on every outline you produce or review, and say which rule a change fixes.
Line of argument (check this first; it is what supervisors usually mean by "lacks logic")
- The introduction states a goal or research question, and the conclusion chapter answers exactly that.
- The order follows the work: problem → background → requirements → concept/design → implementation or experiment → evaluation method → results → discussion → conclusions. Evaluation criteria and method come before results; a design decision is justified where it is made, not in a later chapter.
- Requirements defined early are checked again in the evaluation.
- Background covers what the reader needs for this work, not a catalogue of every tool used.
Logic of the headings
- A subdivision needs at least two parts. A 2.1 without a 2.2 is illogical: merge it into the parent or add a sibling.
- Headings at one level are of equal weight and form a consistent sequence. If "technical evaluation" is a subsection, "economic evaluation" cannot be a sibling chapter.
- Each heading stands on its own and says what the part contains. One-word headings ("Conditions", "Description", "Test rig") usually need sharpening ("Calibrating the measuring devices"); standard names (Introduction, Summary, References, Appendix) are fine.
- Siblings share a grammatical pattern where it helps (all "Preparing …", "Calibrating …", "Mounting …").
- The heading is not part of the text: the first sentence under it must be a complete sentence that would make sense without the heading.
Form (ISO 2145 numbering, the default when the venue sets nothing)
- Arabic numerals, a point between levels, no point after the last number: "2.1 Test setup", not "2.1. Test setup". LaTeX numbers this way by default; Asciidoctor's built-in
:sectnums:prints "2.1." - accept it rather than hand-typing numbers. - Prefer at most 3 numbered levels and at most 9 siblings under one parent; deeper detail becomes unnumbered run-in headings (AsciiDoc
.Titleblock titles, LaTeX\paragraph{}, or bold lead-ins) that stay out of the ToC. - Chapter 0 may hold a preface; n.0 may hold a chapter introduction.
- No punctuation at the end of headings, no full sentences, no citations, no ALL CAPS.
- Abstract, preface, ToC, task statement and declarations get headings but no numbers. The reference list gets a chapter number; appendices get letters (A, B, …). One "Appendix" chapter with A.1, A.2 … usually reads better than many lettered appendices.
Order of parts (ISO 7144, adapt to the institution): cover/title page → (task statement, declaration of authorship, acknowledgements) → abstract → preface → contents → lists of figures/tables/abbreviations/symbols → chapters 1…n → references → appendices → index. Introduction is the first chapter, summary/conclusions the last text chapter. Figures and tables belong next to the text that discusses them, not in an appendix; only bulky material (protocols, drawings, raw data, large tables) goes there.
5. Map content to the outline
For each section of the detailed outline, write one line on what it must deliver (claim, data, figure, table, source). Check that every important statement will have a visualization (figure, table, equation) or at least a list, and that nothing in the outline is there only because material happened to be available. For reports over about 20 pages, collect material per chapter. This content map is what report-drafting works from.
6. Style sheet
For anything longer than a few pages, or written by more than one person, start a style sheet now; consistency problems are cheap to prevent and expensive to fix. Use references/style-sheet-template.adoc as the starting point and fill in what is already decided (terms, spellings, units, numbering, citation style). In teams, agree the outline (finer than 10 points), the style sheet and the toolchain before anyone writes, and announce outline changes immediately.
7. Document skeleton (AsciiDoc or LaTeX)
If the user wants files, generate a skeleton in their markup. Use the project's existing template or class if there is one.
- AsciiDoc:
references/asciidoc-skeleton.md: a master document with the header attributes and one include file per chapter (01-introduction.adoc, …), blank lines between the includes. - LaTeX:
references/latex-skeleton.md:main.texwith the preamble (siunitx, caption, biblatex, cleveref, glossaries) and one\included file per chapter (chapters/01-introduction.tex, …).
Each chapter file holds its heading, its subsection headings with labels/IDs, and a one-line comment per section from the content map. Do not invent body text in a skeleton.
Output
Unless the user asks for only one piece, deliver in this order:
- Task card with open questions (short)
- Title variants with a recommendation
- Core message (one sentence)
- 4-point and 10-point structure, then the detailed outline with the one-line content map
- Notes on which pattern or ordering principle you used, and any rule from section 4 you had to apply
- Style sheet stub and AsciiDoc or LaTeX skeleton, if relevant
When reviewing an existing outline instead, list each problem with the rule it breaks and a concrete fix (rewritten heading or re-nesting), then show the corrected outline. If the report-review skill is installed alongside this one, its linter (python3 ../report-review/scripts/lint_report.py <master.adoc|main.tex>, relative to this skill's directory) catches lone subsections, level skips, hand-typed numbers and heading punctuation mechanically.