Introduction
This chapter was written with the assistance of GitHub Copilot, which expanded on outlined ideas and draft notes provided by the author. The content represents the author’s perspective and has been reviewed for accuracy, but the detailed prose was generated through AI assistance.
This book is a style guide for writing in science, technology, engineering, and mathematics (STEM). Most of its examples come from statistics and data analysis, because statistics and data analysis are the fields that I work in. Most of its rules apply to any writing that explains technical ideas.
1 What the book covers
Most chapters give rules for every kind of technical writing, such as a paper or a set of lecture notes. Four chapters cover one kind of document:
- Paper organization and Preparing a manuscript for submission cover research papers.
- Writing for teaching covers lecture notes, slides, and problem sets.
- Writing for code review and software covers pull requests, issues, commit messages, READMEs, code comments, and release notes.
2 Who the book is for
I wrote this book for students and mentees who are learning to write about their research. I also wrote it for the AI writing assistants that draft and edit prose for me.
Many rules are stated as checks that a reader can apply to a single sentence, so a student and an AI assistant can apply them the same way. For example, the section on demonstrative pronouns asks whether each “this” or “that” is followed by the noun that it refers to. A person or a program can answer that question without knowing what the paper is about.
3 The principle behind the rules
The rules in this book apply one idea from the philosopher Paul Grice. Grice observed that people in a conversation expect each contribution to serve the purpose of the exchange (Grice 1975). He called this expectation the cooperative principle, and he divided it into four maxims (Davis 2024):
- Quantity: be as informative as required.
- Quality: say only what you believe true and can justify.
- Relation: be relevant.
- Manner: be clear, which includes avoiding obscurity and ambiguity, being brief, and being orderly.
A reader of technical writing expects the same cooperation from the author. A sentence that breaks a maxim makes the reader stop and guess what the author meant. Most rules in this book name one way to break a maxim and the fix.
The chapters serve the maxims as follows:
- Quantity:
- “Not more than required”: Conciseness.
- “Not less than required”: Defining terms clearly and the sections of Word choice on naming the object a sentence refers to and following an abstract statement with an example.
- Quality: Citations and evidence, which asks for support for each claim and for checking each source, and Avoiding clichés.
- Relation: the sections of Conciseness on writing about the ideas and not about the document, and the layout of the Results section in Paper organization.
- Manner:
- Obscurity: Word choice.
- Ambiguity: Grammar.
- Brevity: Conciseness.
- Order: the sections on assumptions first in Mathematical notation, on forward references in Paper organization, and on giving the general definition before examples in Defining terms clearly.
The maxims describe what a reader expects. They are not a checklist, because whether a sentence is relevant or informative enough depends on the reader and the purpose of the document. This book therefore states each rule as a check that does not depend on the reader, as the previous section describes, and uses the maxims to explain why each rule exists.
4 How the book is organized
The chapters fall into six groups:
- Terms, notation, and evidence:
- Papers:
- Words and sentences:
- Teaching:
- Software:
- Thinking:
The Summary lists the book’s main rules as a checklist for revising a draft.
5 How to read the book
You can read the chapters in any order. Most sections state one rule and the reason for it, and then show the rule applied to an example. Many sections compare a weaker version of a passage with a stronger one. For example, the Word choice chapter recommends “before” over “prior to”:
❌ Prior to fitting the model, we removed outliers.
✅ We removed outliers before fitting the model.
Definitions, examples, and exercises appear in numbered, colored boxes, so that other sections and other documents can link to them.
Use the book as a reference while you write, and use the Summary checklist when you revise.
6 Further reading
These shorter guides cover some of the same ground:
- Novelist Cormac McCarthy’s tips on how to write a great science paper (Savage and Yeh 2019)
- Elements of style (Nature Physics 2007) - a Nature Physics editorial on scientific writing
- The Pathway to Publishing: A Guide to Quantitative Writing in the Health Sciences (Luby and Southern 2022)
- Secret, actionable writing tips - a thread on X
For who counts as an author, see the ICMJE criteria in Preparing a manuscript for submission.
This list traces back to the Benjamin-Chung Lab Manual by Jade Benjamin-Chung.
For further reading, see the Resources chapter of the UCD-SERG lab manual.
7 Contributing
The book is a work in progress. If a rule is unclear, wrong, or missing, open an issue on the book’s GitHub repository.