Produce Good Technical Writing
Anthony Hornof - 1/24/22
A modern skilled technology expert must be able to communicate their ideas clearly and concisely. Being able to write well can give you great power in your life and in your career.
What is this thing?
One aspect of good writing is making sure that anyone who encounters your document can figure out what it is. To that end, each artifact, document, source code file, README.txt, and so on, that you submit should include, at the top of the file: (1) the names of all authors (in alphabetical order by last name), (2) the date that the document was created or last modified, and (3) a short description of what the thing is. To anyone encountering this document or artifact for the first time, it should be immediately clear what the thing is, who created it, and when.
Some small but important guidelines in technical writing:
- All multi-page documents should have page numbers.
- All acronyms should be unpacked ATFO (at their first occurrence), as was just done here.
Good writing occurs on three levels:
- Structure a piece of writing so that the main ideas are clearly accessible. State the main point of a paper in the introduction. Start each paragraph with a topic sentence. Break the paper or document into sections and give each section a title. Summarize your major findings in a conclusion. Stream-of-consciousness storytelling does not provide a good organizational style.
- Communicate individual ideas effectively. Be thorough but concise. The tone of your writing should be serious and direct, as if you were reporting to your boss at a real job. An informal "chatty" style is not appropriate. Every figure (graph, drawing, or screenshot) should be relevant; should be referenced in the main body of the text; and should have a caption that starts with "Figure x." and then explains what the figure shows.
- All spelling and grammar must be standard and correct.
Organize your ideas in paragraphs. But do not write long run-on stream-of-consciousness paragraphs in which you write down whatever comes to mind, such as a long step-by-step recounting of how you did something. If you find yourself doing this, go back, edit, and add structure. Always proofread your work. Do not write paragraphs that are lists with lots of text jammed together, as as done in the next paragraph. The next paragraph has the exact same words as shown in the three-item list above. Notice how it is much easier to understand the ideas in the three-item. The next paragraph is much harder to understand:
- Good writing occurs on three levels. Structure a piece of writing so that the main ideas are clearly accessible. State the main point of a paper in the introduction. Start each paragraph with a topic sentence. Break the paper or document into sections and give each section a title. Summarize your major findings in a conclusion. Stream-of-consciousness storytelling does not provide a good organizational style. Communicate individual ideas effectively. Be thorough but concise. The tone of your writing should be serious and direct, as if you were reporting to your boss at a real job. An informal "chatty" style is not appropriate. Every figure (graph, drawing, or screenshot) should be relevant; should be referenced in the main body of the text; and should have a caption that starts with "Figure x." and then explains what the figure shows. All spelling and grammar must be standard and correct.
Actively work to improve your writing.
Take writing classes. Study books such as:
- Huckin & Olsen (1983). English for science and technology.
- Kane. (2000). The Oxford essential guide to writing.
- Lebrun. (2007). Scientific writing: A reader and writer’s guide.
- Turabian. (2018). A manual for writers of research papers, theses, and dissertations.
PDFs of some the best chapters from these books are available on the course Canvas site under Files / Technical Writing.
Access the drop-in
writing tutoring at the Teaching and Learning Center.