1. Learning Outcomes

1. Apply the principles of clear, concise and precise technical prose, and revise a verbose passage into one.
2. Conduct a structured audience analysis and calibrate tone, vocabulary and depth to a reader persona.
3. Select a structural template — IMRaD, BLUF, modular, pyramid — and justify the choice for a given document.
4. Distinguish the major categories of technical report and construct a complete report following the IMRaD convention.
5. Apply IEEE, ACM and APA referencing correctly and consistently, including in-text citations and bibliography entries.
6. Design tables and figures that are self-sufficient, accessible and governed by the data-ink principle.

2. Why Reporting Is Part of the Method

Computer science research is increasingly collaborative, interdisciplinary and globally distributed. Whether the deliverable is a thesis, a conference paper, a white paper, an internal memorandum or a software release note, the artefact’s value depends on how effectively it communicates its findings. A technically brilliant algorithm with a poorly documented evaluation is, in practical terms, indistinguishable from an undocumented idea.

Robert Day’s How to Write and Publish a Scientific Paper frames technical writing as a moral obligation: peer review is impossible without a complete, reproducible account of the method. Reporting is therefore not a post-hoc administrative duty appended to the research; it is an integral part of the research method itself.

3. Core Vocabulary

4. Principles of Clear and Concise Writing

The foundational principles may be consolidated into seven interrelated tenets. Every word in a technical document must earn its place.

4.1 Brevity Through Precision

Conciseness is not brevity at the expense of meaning; it is the elimination of redundancy, hedging and verbose construction.

4.2 Active Voice Predominance

The active voice assigns agency to the subject and produces shorter, more vigorous sentences. Passive voice is legitimate when the actor is unknown, irrelevant, or less important than the action.

• Passive (acceptable, emphasis on method): “A binary search tree was implemented in Python.”
• Active (preferred for clarity): “We implemented a binary search tree in Python.”

4.3 Specificity and Quantification

Replace vague qualifiers with concrete, measurable statements. “Many researchers have studied this problem” is less informative than “Twenty-seven studies between 2015 and 2024 have examined this problem.”

4.4 Logical Sequencing

Information should flow in a sequence that mirrors the reader’s cognitive progression: from known to unknown, general to specific, problem to solution, claim to evidence.

4.5 Economy of Modifiers

Adjectives and adverbs should describe, not ornament. Very, really, quite, basically and essentially should be excised unless they carry precise technical meaning.

4.6 Front-Loading Key Information

Place the principal conclusion or finding at the beginning of each paragraph and section. This inverted pyramid structure respects the time constraints of professional readers and facilitates scanning.

4.7 Revision as a Non-Negotiable Stage

Professional technical documents are drafted, revised, peer-reviewed and edited multiple times. The first draft is rarely the final version. Strunk and White’s axiom — “Vigorous writing is concise” — remains the cornerstone, extended in the digital era to multimodal documents that integrate prose, diagrams, equations and code.

4.8 Worked Revision

5. Audience Analysis

The cardinal rule of technical writing is to write for the reader, not for oneself. Most unreadable student writing is writing addressed to its own author. Effective audience analysis proceeds through four dimensions.

5.1 Demographic Profile

Identify the reader’s disciplinary background, educational level, professional role and cultural context. A computer science undergraduate, a software engineer in industry, a funding agency reviewer and a domain expert in bioinformatics represent radically different audiences.

5.2 Prior Knowledge

Assess what the audience already knows. Technical documents must not insult expert readers with elementary explanations nor overwhelm novices with unexplained jargon. This calibration is achieved through a layered approach: brief contextual reminders for established concepts, detailed exposition for novel contributions.

5.3 Purpose and Use Context

• To learn — tutorial contexts, introductory material.
• To apply — operational manuals, API documentation.
• To evaluate — peer review, proposal assessment, hiring decisions.
• To cite — scholarly reference in subsequent work.

Each purpose shapes the depth of explanation, the inclusion of examples and the prominence of conclusions.

5.4 Reading Conditions

Consider whether the document will be read on screen or in print, linearly or by scanning, in a single session or intermittently. Web-based technical documents demand scannable subheadings, bullet points and visual hierarchy.

5.5 The Reader Persona

A useful heuristic is to construct an explicit reader persona — a hypothetical composite of the target audience — and to write as if addressing that persona directly.

6. Structuring Technical Content

Structure is the skeleton that enables the reader to navigate complex information. Four canonical structures dominate technical writing in computer science.

6.1 The IMRaD Structure

The Introduction–Methods–Results–and–Discussion structure is the prevailing template for empirical research papers in computer science and engineering, and the basis of the ACM and IEEE publication templates.

• Introduction — establishes context, surveys related work, identifies the research gap, states the contribution.
• Methods — describes the algorithms, systems, experimental setups or theoretical frameworks employed.
• Results — reports the empirical or analytical findings with appropriate quantitative detail.
• Discussion — interprets results, acknowledges limitations, positions the work within the broader literature.

6.2 The BLUF Structure

Bottom Line Up Front, originating in military and executive communication, places the key conclusion at the document’s outset, followed by supporting evidence. It is particularly effective for proposals, executive summaries and progress reports.

6.3 Modular and Hierarchical Structures

Technical reports, software documentation and standards documents frequently employ modular structures with discrete, numbered sections and subsections. The IEEE conference template prescribes a two-level hierarchy with Roman-numeral main headings and alphabetic subheadings.

6.4 The Pyramid Principle

Popularised by Barbara Minto, the pyramid principle requires that ideas be grouped, summarised and supported hierarchically: the central thesis appears first, followed by grouped supporting ideas, each further supported by evidence. Formally this is a tree

where r is the root thesis and each S_i is a sub-thesis supported by its own subtree of evidence. The formalism aids both writing and logical validation: it lets you check the argument independently of the prose.

7. Types of Technical Report

Reports vary by audience, purpose, formality and length. A robust typology matters because each type carries its own conventions of tone, citation density, visual aids and review process.

7.1 Classification by Purpose

7.2 Classification by Formality and Length

• Formal reports — printed, bound, with title page, table of contents, executive summary and full bibliography. Used for theses, sponsored research and governmental submissions.
• Informal reports — short, often single-section, delivered as memos or technical notes for day-to-day engineering decisions.
• Short (2–10 pages) — trip reports, evaluation summaries, memos. Medium (10–30 pages) — progress reports, laboratory investigations, internal white papers. Long (30+ pages) — final research reports, master’s theses, dissertations.

7.3 Selecting the Appropriate Type

8. Canonical Structure of a Report

8.1 Front Matter — Title Page

The title page is the report’s single most-read page. It should contain a specific, descriptive title (often 8–15 words, avoiding abbreviations and colloquialisms); the authors’ names, institutional affiliations and contact details; a report number or version identifier; and the submission date with any sponsorship acknowledgements.

8.2 Front Matter — Abstract

The abstract is a self-contained micro-representation of the entire work, conventionally 150–350 words, following a four-element convention:

1. Background (1–2 sentences) — the domain and the gap.
2. Objective (1 sentence) — the specific aim.
3. Methods (1–2 sentences) — how the objective was addressed.
4. Results and conclusion (2–3 sentences) — the principal findings and their significance.

Front matter is completed by the table of contents, list of figures and list of tables — generated automatically in LaTeX or Word, with dot leaders, right-aligned page numbers, and a depth of three heading levels.

8.3 The IMRaD Body — Introduction

The introduction establishes the why. A widely recommended internal structure follows the funnel pattern:

1. Broad context — situate the problem within a wider field.
2. Specific problem — narrow to the precise gap addressed.
3. Prior work — summarise the most relevant prior studies and how they fall short.
4. Research question / hypothesis — state explicitly.
5. Contribution — list the paper’s claimed contributions.
6. Outline — describe the structure of the remainder.

8.4 The IMRaD Body — Methodology

The methodology establishes the how. In computer science it is sometimes called Approach, Method or Design. Three principles apply.

1. Reproducibility. Another competent researcher should be able to repeat the study from your description. Provide equations, hyperparameters, hardware specifications, software versions, dataset identifiers and evaluation protocols.
2. Justification. Every methodological choice should have a rationale citing prior art or a stated trade-off.
3. Boundary conditions. State explicit assumptions — for example, “all experiments were run on a single NVIDIA A100 GPU with CUDA 12.2”.

A common structural sub-template: datasets; proposed model or algorithm (with formal definitions and diagrams); experimental setup (baselines, metrics, hyperparameters); evaluation protocol (cross-validation, statistical tests, seeds); implementation details (libraries, compute, runtime).

8.5 The IMRaD Body — Results

The results section reports what was observed without interpretation. Conjugate every statement of finding with the experiment that produced it.

• Use past tense; avoid evaluative adjectives.
• Present numerical results in tables when precise comparison is needed, and in figures when trends or distributions dominate.
• State sample sizes, variances and significance levels.
• If a result contradicts a hypothesis, report it. Do not omit it.

A useful pattern: each outcome is introduced with a topic sentence, supported with a table or figure, then quantitatively restated — “Table 3 indicates that the proposed model achieves a 7.4 percent improvement in mean F1 across the ten folds (p < 0.01, Wilcoxon signed-rank).”

8.6 The IMRaD Body — Discussion and Conclusion

The discussion extracts meaning from the results, in six recommended components: summary of principal findings; interpretation anchored in theory or prior work; comparison with prior work; implications, practical and theoretical; limitations, honestly articulated as threats to validity; and future work, concrete and testable.

The conclusion is short — often half a page to a page — and answers what did we learn? Conventionally: one paragraph recapitulating the motivation, one summarising the principal contribution, one on broader impact or future directions. Conclusions introduce no new data and no new citations.

8.7 Back Matter

• References / bibliography — see Section 10.
• Appendices — proofs, full dataset statistics, code listings, additional tables.
• Acknowledgements — funding bodies, advisors, technical contributors.
• Author contributions and conflict-of-interest disclosures — mandatory in many venues.

8.8 Micro-Structure at Paragraph and Sentence Level

• Topic sentence first. Each paragraph opens with a sentence stating its claim; supporting sentences follow.
• Signposting. Use phrases such as “In this section, we…”, “As a consequence”, “By contrast”, “We next evaluate…”.
• Concrete nouns, precise verbs. Replace “a thing”, “very”, “a lot of” with “the proposed classifier”, “increases by approximately 4 percent”, “evaluated on five datasets”.
• Consistent tense. Past tense for completed work; present tense for established facts and your own claims (“Table 3 shows…”).
• Voice. Computer-science writing tolerates both, but modern style guides (ACM 2017) encourage the active voice — “We trained five models” rather than “Five models were trained”.
• Definitions on first use. Every acronym (CNN, LoRA, BLEU) is defined once; every symbol in a displayed equation is defined in the preceding text.

9. Language, Grammar and Formatting Conventions

9.1 Register, Terminology and Ambiguity

Technical writing occupies a middle register between colloquial speech and formal academic prose: impersonal yet engaged, authoritative without being condescending. Personal pronouns are acceptable and often encouraged in computer science publications. Terms such as throughput, latency, concurrency, idempotent and monotonic carry specific technical meanings that must not be conflated with their general-language equivalents. When introducing a term, provide a parenthetical gloss: “We employ a suffix array (a sorted array of all suffixes of a string) to enable substring search in O(n log n) time.”

Inclusive and neutral language. Avoid gendered pronouns when the referent is generic; prefer singular they, “the user”, or restructuring the sentence. Avoid language that perpetuates stereotypes or excludes groups.

9.2 Grammar Essentials

• Subject–verb agreement across intervening phrases. Incorrect: “A collection of algorithms are presented.” Correct: “A collection of algorithms is presented.”
• Consistent tense. Present for established knowledge, past for specific completed actions; consistency within a document is paramount.
• Parallel structure. Incorrect: “The system is fast, reliable, and it is also easy to use.” Correct: “The system is fast, reliable and easy to use.”
• Articles. Use the when the referent is unique or previously specified; a / an when introducing a new, non-specific referent.
• Punctuation precision. Serial comma before the final item of three or more; em dash for parenthetical emphasis; quotation marks for direct quotation only, with italics for emphasis; semicolons between related independent clauses.
• Sentence length. Aim for an average of 15–20 words; break longer sentences at natural semantic boundaries and vary length deliberately.

9.3 Formatting Conventions

• Headings should be descriptive, parallel in grammatical form and hierarchically consistent — “3. Methodology / 3.1 Data Collection / 3.2 Preprocessing / 3.3 Model Training”. Avoid generic headings such as “Body” at lower levels; the heading itself should signal the section’s content.
• Figures and tables must be numbered sequentially, captioned so as to be self-contained, referenced explicitly in the surrounding prose, and legible when extracted from the document.
• Equations should be numbered when referenced subsequently, with variables defined on first appearance.
• Lists — bulleted for unordered enumerations, numbered for sequential or ranked items; avoid nesting beyond two levels.
• Code listings — monospaced font, consistent indentation, introduced by explanatory prose; use LaTeX’s listings package, Markdown code fences, or the ACM/IEEE listing environments.

10. Referencing Styles

Referencing has three components: the citation in the text, the bibliography entry in the reference list, and the style — the rules connecting them. Confusing the three is why student reference lists fail internal consistency.

10.1 Why Citation Discipline Matters

• Attributes intellectual credit.
• Strengthens the argument by anchoring claims to prior work.
• Protects against plagiarism accusations.
• Enables readers to verify and build upon the work.

10.2 The Major Styles

AMA is used in medical research and ACS in chemistry, occasionally in computational chemistry. Chicago has two variants: author–date for the sciences and notes and bibliography for the humanities.

10.3 Choosing and Staying Consistent

11. Citations in Detail

11.1 Quotation, Paraphrase and Summary

• Direct quotation reproduces the original wording, enclosed in quotation marks, with a page number. Use sparingly in technical writing.
• Paraphrase restates the idea in your own words, with citation. Preferred over quotation in most CS writing.
• Summary condenses a longer work; cite the source as a whole.

11.2 Narrative versus Parenthetical Citation

• Narrative: “Vaswani et al. (2017) demonstrate that…” — emphasises the author.
• Parenthetical: “…has been demonstrated (Vaswani et al., 2017).” — emphasises the finding.

Most style guides require three or more authors to be shortened to the first author plus et al. in parenthetical usage (APA 7). IEEE and ACM list all authors up to a limit, commonly six, before et al.

11.3 Components of a Bibliography Entry

1. Author(s), with full first names or initials per the style.
2. Year of publication.
3. Title of the work (article, chapter, book).
4. Container — journal name, conference proceedings, book title.
5. Volume, issue, page range.
6. Publisher and location.
7. Identifier — DOI, arXiv ID, ISBN or URL.

11.4 Five Common Citation Errors

11.5 Reference Management Tools

A reproducible workflow: maintain a single .bib file, generate the bibliography at compile time, and output a chosen .bst style.

12. Visual Aids

Visual aids convert raw data into knowledge and shorten the path between claim and evidence. The technical-report ethos requires that every visual element be self-sufficient — interpretable without recourse to the prose.

12.1 Table or Figure?

• Use a table when the reader must read precise values, when the data are textually heterogeneous, or when the comparison is between discrete categories.
• Use a figure when the reader must apprehend a trend, a distribution or a spatial relationship.

Edward Tufte’s The Visual Display of Quantitative Information introduces the data-ink ratio: maximise the proportion of ink devoted to actual data and minimise decorative elements — chartjunk — such as heavy gridlines, redundant 3D and ornate borders.

12.2 Charts and Their Appropriate Use

12.3 Tables — Construction Rules

• Number and title above the table: “Table 3: Mean F1 across five folds.”
• Right-align columns of pure numbers; left-align text columns; align decimals.
• Avoid vertical rules. Use horizontal rules only at the top, beneath the header, and at the base — the booktabs convention.
• Put units in column headers: Accuracy (%), Latency (ms).
• Highlighting best results in bold is acceptable; red highlighting is discouraged for colour-vision accessibility.
• The caption explains what is shown, the experimental setting, and any symbol definitions.

12.4 Figures — Construction Rules

• Numbered sequentially across the whole document.
• Caption is descriptive, not interpretative: “Figure 4: ROC curves for four models”, not “Figure 4: Model X is best”.
• Resolution: at least 300 dpi for print, 150 dpi for screenshots. Vector graphics preferred — plots saved as .pdf or .svg scale cleanly.
• Colour-blind-safe palettes: viridis, cividis, ColorBrewer. Never red–green contrasts alone.
• Fonts inside figures should match body text size, typically 8–10 pt.
• Avoid dual y-axes unless the relationship is meaningful and explained.

12.5 Algorithms, Code and Diagrams

• Algorithms — use a structured LaTeX environment (algorithm, algorithmic); number every line for cross-reference; include input/output specification and a complexity comment.
• Code listings — syntax-highlighted monospace (listings, minted); limit to excerpts that highlight the contribution; specify language and version.
• Diagrams — sequence diagrams for inter-process communication; UML class diagrams for object-oriented design; architecture or block diagrams for system composition; entity-relationship diagrams for databases. Stick to standard notation: a non-standard diagram is worse than no diagram.

13. Worked Example: A Mini Report Outline

A student prepares a final-year report on Energy-Efficient Inference Scheduling on Edge Devices. The structure applies the lecture’s principles across the whole writing lifecycle.

1. Title page — project title, student, supervisor, programme, date.
2. Abstract — background, objective, methods (Raspberry Pi benchmarks), result (15% energy reduction), significance.
3. Table of contents.
4. Introduction — growth of edge computing, the energy challenge, prior scheduling literature, the stated gap.
5. Methodology — hardware specifications, baseline and proposed scheduler, energy measurement via INA219 sensor, workload suite.
6. Results — tables of energy consumption, latency and throughput; figures of latency-versus-energy Pareto fronts.
7. Discussion — trade-off interpretation, comparison to the Round-Robin baseline, limitations of single-board scope.
8. Conclusion and future work.
9. References in IEEE style.
10. Appendices — full measurement logs, code, datasheets.

14. Common Pitfalls

14.1 In Technical Writing

1. Verbal inflation — elaborate constructions for simple ideas (“utilize” for “use”, “in order to” for “to”).
2. Hedging without commitment — “might possibly perhaps indicate” dilutes claims.
3. Anthropomorphism — “the program wants to terminate”.
4. Inconsistent terminology — “client”, “customer” and “user” used interchangeably for the same entity.
5. Acronym overload — define every abbreviation except universally understood ones (CPU, API), and limit density to roughly one acronym per sentence.
6. Neglecting figures and tables — describing in prose what a graphic communicates more efficiently.
7. Misjudging prior knowledge — either over-explaining or under-explaining.

14.2 In Report Writing

• Title–content mismatch — promises in title and abstract not delivered in the body.
• Methodology gap — insufficient detail to allow replication.
• No clear research question — even sound methods cannot redeem an aimless study.
• Results–discussion confusion — commentary buried inside results paragraphs.
• Inconsistent reference formatting.
• Purposeless visual aids — decorative illustrations that do not advance the argument.
• Sweeping overgeneralisation — extrapolating from n = 10 experiments.
• Plagiarism of structure — paraphrasing a published paper too closely even with citations.
• Spelling and grammar errors in the abstract — the section reviewers read most closely.

15. Summary

• Technical writing is a purposeful, audience-oriented and structured form of communication, distinct from academic essay writing and from creative prose.
• Clarity and conciseness are achieved through deliberate word choice, active constructions and rigorous revision. Conciseness creates room for substance.
• Audience analysis across four dimensions calibrates depth, tone and content selection; a reader persona operationalises it.
• Canonical structures — IMRaD, BLUF, modular, pyramid — are chosen deliberately, not defaulted into.
• Technical reports come in nine principal types, selected by audience, purpose, review process and archival value.
• Referencing is the connective tissue of academic discourse. IEEE is the CS default; the chosen style must be applied consistently throughout.
• Visual aids are evidence, not decoration. They must be self-sufficient, accessible and governed by the data-ink principle.

16. Exam Preparation

16.1 Short-Answer Questions

1. Define technical writing and distinguish it from academic essay writing. 3 marks
2. List any five principles of clear and concise writing with one-sentence justifications. 5 marks
3. What is the IMRaD structure? Identify a context in which it would be inappropriate. 3 marks
4. Explain the difference between cohesion and coherence with examples. 3 marks
5. What is a reader persona, and how does it assist audience analysis? 2 marks
6. List any three types of technical report and one defining feature of each. 3 marks
7. What is the difference between a narrative and a parenthetical citation? Give one example of each in APA style. 3 marks
8. State the rule for citing a work with three or more authors in APA 7. Does IEEE follow the same rule? 2 marks
9. Why is a high data-ink ratio important for figures? 2 marks

16.2 Medium-Answer Questions

1. Rewrite the following passage to improve clarity, conciseness and precision: “It has been demonstrated by researchers in the past that there exists a problem with the way that systems which are based on blockchain technology are able to handle situations where there are a very large number of users trying to use the system at the same time, which is something that our research aims to address.” 5 marks
2. Construct a reader persona for a technical report on quantum-resistant cryptography intended for a government cybersecurity policy committee. 5 marks
3. A colleague submits the following paragraph describing an algorithm. Identify at least four issues: “The function takes the data and then it processes it very quickly, basically using recursion. It’s a really good function that was written by the team. The function, which is written in python, runs in linear time usually but sometimes its quadratic when there’s like a lot of data.” 6 marks
4. Construct the IEEE reference for a book by Hopcroft, Motwani and Ullman titled Introduction to Automata Theory, Languages, and Computation, third edition, published by Pearson in 2006. 3 marks
5. Redesign the following figure description to comply with chart hygiene principles: “Pie chart of programming languages used: Python 50 percent, Java 30 percent, C++ 15 percent, other 5 percent.” Identify at least three concerns and propose remedies. 6 marks

16.3 Long-Answer Questions

1. Compare and contrast the BLUF and IMRaD structures. Under what circumstances would each be more appropriate, and why? Justify your answer with reference to a specific document type in computer science research. 10 marks
2. You are writing a 25-page progress report on a sponsored machine-learning research project. Produce a section-level outline using the IMRaD convention and justify the order, length and content of each section. 10 marks
3. Critically evaluate the choice of IEEE referencing over APA for a computer science thesis. What are the practical and ethical implications? 8 marks
4. Discuss the proposition that “visual aids are evidence, not decoration”, with reference to the data-ink ratio, self-sufficiency and accessibility. 10 marks

16.4 Think-and-Apply

17. Suggested Reading

1. Strunk, W., & White, E. B. (2000). The Elements of Style (4th ed.). Longman.
2. Alred, G. J., Brusaw, C. T., & Oliu, W. E. (2020). The Technical Writer’s Companion (5th ed.). Bedford/St. Martin’s.
3. Minto, B. (2009). The Pyramid Principle: Logic in Writing and Thinking (3rd ed.). Financial Times Prentice Hall.
4. Day, R. A., & Gastel, B. (2016). How to Write and Publish a Scientific Paper (8th ed.). Cambridge University Press.
5. Schimel, J. (2012). Writing Science: How to Write Papers That Get Cited and Proposals That Get Funded. Oxford University Press. The most useful single book for a research student in this area.
6. Whitesides, G. M. (2011). “Writing a Paper.” Advanced Materials, 23(11), 1321–1323.
7. Tufte, E. R. (2001). The Visual Display of Quantitative Information (2nd ed.). Graphics Press.
8. American Psychological Association. (2020). Publication Manual of the APA (7th ed.).
9. IEEE. (2018). IEEE Editorial Style Manual. Available at https://ieeeauthorcenter.ieee.org/
10. ACM. (2017). ACM Master Article Templates and Style Guide. Available at https://dl.acm.org/