A Guide to Technical Writing: Tips for Students and Professionals

Technical writing is a crucial skill for students and professionals alike. Whether you’re crafting a thesis, a research paper, or a technical report, clear and effective communication is essential for conveying your ideas and achieving your goals. This guide provides practical advice and guidance to improve your technical writing skills and produce high-quality documents.

I. Understanding Your Audience and Purpose

Before you begin writing, it’s important to consider your audience and the purpose of your document.

Know Your Audience: Are you writing for experts in your field, or a more general audience? Tailor your language and level of detail to their knowledge and understanding. A common fault is assuming too much knowledge. Consider students at the same stage, but who haven’t done their thesis in your area. You can assume them to have passed the basic operating-systems course but know nothing about the area beyond that.
Define Your Purpose: What are you trying to achieve with your writing? Are you informing, persuading, or instructing? Your purpose will guide your content and structure. Make sure the whole paper has a clear and consistent message. You should be able to state this message in one short sentence. Then stick to it, in the abstract, in the intro, in the body, in the conclusion.

II. General Advice for Effective Technical Writing

These general hints on technical writing are followed by more specific guidelines aimed at students writing their thesis.

Maintaining User State

One of the most crucial aspects of good technical writing is maintaining “user state.” Like a good operating system, a good writer is fully aware of the relevant state in the mind of the reader at any point of the paper/report. The writer should ensure that the reader’s mental state is kept coherent as they systematically build up their understanding and knowledge of the work, starting from a reasonable initial state. Ensure that at any point in the paper, you don’t expect more knowledge from the reader than the union of the initial state and what you’ve told them so far.

Clarity and Conciseness

The two most important qualities of good technical writing are clarity and conciseness.

Be Clear: Use precise language and avoid jargon. Define any technical terms you use. Ensure that each sentence is unambiguous in its meaning. Make sure your formulation is precise. Make sure every paragraph has a clear and unique purpose. Make sure a paragraph is homogeneous in its message (talks about one thing only) and paragraph breaks correspond to changes of points.
Be Concise: Get to the point quickly and avoid unnecessary words. Use short sentences and paragraphs. In a paper you can’t afford to be waffly. Reviewers expect a fair amount of meat in the 12 or so pages you’ve got, and if you waffle, you won’t fit enough meat in. Furthermore, bloated prose tends to be harder to read. If something can be said in a sentence or in a paragraph, say it in a sentence.

Structure and Organization

A well-structured document is easier to read and understand.

Use Headings and Subheadings: Break up your text into logical sections with clear headings and subheadings. Make sure each section (at any level) has a clear and coherent purpose and message. (Yet avoid sections getting too long, preferably not more than a single column, if at all possible not longer than a page, else break it up or sub-structure it.)
Use Lists and Tables: Present information in a clear and organized manner using lists and tables.
Strategic Redundancy: Small, strategic doses of redundancy help (but don’t go overboard, as unnecessary redundancy annoys the reader as it wastes their time and detracts from the essentials). Use this to establish context.
1. Say what you’re going to say,
2. say it,
3. say what you just said.

Visual Aids

Visual aids can enhance your writing and make it more engaging.

Use Diagrams and Figures: Illustrate complex concepts with diagrams and figures. A figure must be related to what you are presenting and help understanding, else it’s a useless filler.
Use Captions: Provide clear and concise captions for all visual aids.

Revision and Editing

Always revise and edit your work before submitting it.

Proofread Carefully: Check for errors in grammar, spelling, and punctuation.
Get Feedback: Ask a colleague or friend to review your work and provide feedback.
Take Feedback Seriously: This means not only blindly fixing marked-up issues, but think about the comments. Particularly if the same mistake gets highlighted repeatedly, think about why you make this mistake, and how you can avoid making it again.

III. Thesis Writing: Specific Guidelines

This section focuses on theses (undergraduate), as they tend to be the ones needing advice. However, there are late-stage PhD students who are also well advised to read this.

General Advice

First rule is think before you write. Have an outline, know what you want to write about in each part, and how to approach it. Also, be careful how you write. Ensure that the thesis is well-readable. This implies following the general style and grammar rules, violating those detracts the reader and makes the text harder to follow.

Structure and Coherence

Make sure your thesis is well structured, that each major section does what it is supposed to do, and that the whole thing hangs together. The basic structure is often as follows (but other structures are possible). Use common sense!

Title: Use a descriptive title for your work. Don’t use a title that promises more than you’ll deliver, don’t use a title that implies something different from what you’ve done.
Abstract: A short (1–3 paragraph) summary of the work. Should state the problem, major assumptions, basic idea of solution, results.
Introduction: Introduce the problem (gently!) Try to give the reader an appreciation of the difficulty, and an idea of how you will go about it.

Remember, the intro is the first thing that is being read, and will have a major influence on the how the reader approaches your work. If you bore them now, you’ve most likely lost them already. Make sure you pick up any threads spun in the introduction later on, to ensure that the reader thinks they get what they have been promised.
Exposition of Problem: The basic problem should have been stated in the intro, here is the place to go into detail. Give a thorough and complete discussion of the problem, enough so an educated reader whose speciality is outside yours can appreciate that you’re trying to attack an interesting problem, and also appreciates what’s interesting about it.
Literature Review (Related Work): This is really important. If you cannot demonstrate that you know, and understand, what others have done, you only demonstrate that you’re clueless.
Design of Your Solution: Having explained the problem, and what others have done in similar situations, now explain your approach. Again, give a general overview of your design first, and then go into detail (i.e.use a top-down approach).
Implementation: In many (not all cases) there is a clear difference between the general approach (design) and its implementation in your particular circumstances. The design may be more general than what you can do given time and resources. Avoid mixing up discussions of design and implementation! Design is first, implementation later.
Experiments: A thesis almost always has an experimental part, typically some benchmarking.
Discussion: Discuss and explain your results. Show how they support your thesis (or, if they don’t, come up with a damned good reason real quick).
Conclusions: Discuss what you/we can learn from the results. Draw some real conclusions. Identify all shortcomings/limitations of your work, and discuss how they could be fixed (“future work”).

IV. Conference Paper Writing: Specific Guidelines

Conference paper writing are related, they both are technical presentations of work done. The main differences between a paper and a thesis are:

A paper is obviously much more concise.
A conference paper is pass/fail (with a very high failure rate).

General Rules

As far as general writing style is concerned, I find it useful to think in the below Two Cs. Most papers I find poorly written (as opposed to technically deficient) fall down on one or both of them, or on structure (which is separately addressed below).
Be clear. Make sure that at every level, what you are writing conveys a clear and unambiguous message.
Be concise. In a thesis you can afford to be waffly (although it won’t endear you to the reader), in a paper you can’t.

Expectations on systems papers

What characterises systems is that ideas are considered cheap, and may get you a workshop paper, but nothing more. For a real paper you need a system, and evaluate it. In the end, it comes down to making a convincing case of solving a real problem. You need to identify a problem, offer a solution, and show that you actually solve the problem.

Structure

Technical papers tend to have a certain structure. In the systems community, there is a fairly clear consensus on what the structure should be.
Title make sure the title is informative! It should tell me whether this is about distribution or inside the node, whether it is about security or performance, whether it’s about abstractions or implementation issues, whether it’s theory-heavy or purely practical.
Abstract the abstract serves a single purpose: to attract the right reviewers.

The critical importance here is to attract the right reviewers, those who really understand (and appreciate) what you’re up to. A core rule for the abstract is keep it short!
Introduction Here you need to convince the reader that you have identified a real problem (which includes motivating why it is relevant!) and outline your approach to solving it. And make it clear that you have actually solved it! Cut to the chase! I want to see that what you are saying makes sense. In summary, the intro must convey that you meet the general criteria for a systems paper: identified a real problem (motivate that it is real and interesting), come up with a solution (give a rough idea what the solution looks like) and actually solved the problem (high-level summary of results).
Background This is where you go into details about the motivation for your work, and any other background required to understand it.
What you’ve actually done The best general advise here is to be concise, precise and easy to follow. Remember, a PC member might read 20–30 papers. Keep them interested. If a paper is boring, or hard to follow, it’s got an uphill battle to be accepted.
Evaluation You now have to prove that you’ve actually done it (solved your problem) and done so in a convincing way. This means finding the right evaluation criteria—meaningful benchmarks which demonstrate that you have something useful.
Related work The most important role of the related-work section is to show that you know the field, and are familiar with all the relevant contributions made by others.
Conclusions and Future Work This is where you summarise what you’ve achieved.

Formatting

Conferences tend to be quite prescriptive about the formatting of submissions. Observe all formatting rules! Don’t mess with margins, font sizes or baseline skip!

V. Common Mistakes to Avoid

This section lists things that people most frequently get wrong.

Passive Voice

Overuse of passive voice is one of the most annoying mistakes. Avoid it!

Buzzwords

Buzzwords are annoying to the informed reader and should be avoided, they create the impression of bragging (and often outright cluelessness). Shy away from such words!

Chart Abuse

The term chart abuse refers to all sort of ways of using graphs in an (intentionally or not) misleading way. In science, being misleading is a form of intellectual dishonesty.

Spelling

There is no excuse for presenting a draft that hasn’t gone through a spell checker. If you’re too lazy to do this, then I’m too lazy to read your work.

Capitalization

Don’t Randomly capitalize Words. Looks Ridiculous, doesn’t it?

Commas

Commas have a vital role to play in longer sentences, separating information into readable units, and guiding the reader as to the relationship between phrases and items in a series.

Colons (and Lists)

Colons are used to indicate that examples or specific details are to come.

Definitions/Introductions of New Terms

Use italics when introducing new terms. This makes it easy for the reader to find the definition again, particularly when not having the time to read the paper in one shot.

Acronyms and Initialisms

Technically the difference between the two is that acronyms you pronounce as a word (FOSS) while initialisms are pronounced as individual letters (UNSW). Properly define all acronyms on first use (except maybe those really everybody knows, such as CPU). An acronym is normally introduced by following the full term by the abbreviation, as in address mappings are cached in the translation look-aside buffer (TLB).

Units of Measurement and Their Prefixes

Computer people are particularly notorious (others would say clueless) with respect to improper use of unit symbols. If you think it is not, can you confidently tell me whether a Gigabit Ethernet is supposed to have a bandwidth of 109 b/s or 230 b/s?

Headings

Capitalize or not? Generally speaking, only top-level or, for larger documents, second-level section headings should be capitalized. For other headings capitalize the first word (of course), but otherwise nothing you wouldn’t capitalize in normal text.

Excess Digits (Pseudo Accuracy)

A common annoyance is people quoting results with three or four digits accuracy, when the real accuracy is at best a few percent. This is misleading, as it gives the appearance of something (accuracy) that isn’t there.

Percentage vs Percentage Points

If your overhead (e.g. measured as relative latency increase over a reasonable baseline) changes from 20% to 30%, then this does in no way constitute a 10% increase, it’s a 50% increase in overhead!

Footnotes

First rule: use them sparingly. Many disciplines (especially humanities) use them for citations, we don’t.

Hyphens, En-dashes and Em-dashes

These are three kinds of dashes used in text:

The hyphen is used for hyphenation (breaking words at the end of line), as well as for compound words.
The en-dash is used for ranges
the em-dash is used as a separator, somewhat similar to a semicolon.

Citations and Bibliography

Abbreviating conference and journal names is acceptable where you have tight space constraints (typically for conferences and workshops) but not acceptable elsewhere. Independent of citation style, the following rules should be followed: don’t abuse the category technical report; citing web pages is often unavoidable.

Equations

Equations are not floats, even though the reference mechanism is similar. Instead, they are considered part of the prose.

Inclusive vs Royal “We”

Scientific literature is written in the first person plural (“we form”), and theses are no exception. This is meant to include the reader in the proceedings (“we” in the sense of “you and I together”).

VI. Conclusion

Mastering technical writing is an ongoing process. By following the tips and guidelines in this guide, you can improve your skills and produce clear, effective, and engaging technical documents. Remember to always consider your audience, define your purpose, and revise your work carefully. Good technical writing is essential for success in academic and professional settings.