Great work is worthless without writing: Leslie Lamport, 2013 of the Turing Award (the Nobel Prize of Computer Science), spent most of his 2017 commencement address at Brandeis pleading with students for better communication:

If you succeed in attaining a position that allows you to do something great, if you do something that really is great, and if you realize that it’s great, there’s still one more hurdle: You have to convince others that it’s great. This will require writing.

Writing Advice

Simply put: if you are bad at writing or communicating your ideas, your ideas don’t matter. So, what is clear, effective, technical communication?

  • Improve your style: Google technical paper or systems design doc Look at the structure of the documents. There is a clear structure that is not just reflected in the content, but through section titles, through lists, and through figures. The important information is easy to locate. Your goal is to communicate as clearly and efficiently as possible.

    • Does your document have clear sections and subsections that communicate the structure of your writing?
    • When you are communicating a list of items, are you using a bullet-point (or numbered) list?
    • Do key words or definitions stand out (by bolding, italicizing, etc.)?
    • When appropriate, are there captioned images that represent the ideas you’re trying to communicate? Don’t tell me about your design, show me. Don’t just tell me about your technical system, create a visual overview of the modules.
    • Does your document look like a professional document? Don’t double space these documents. Find a good style template to use.

  • Look at our course’s writing rubric: I have it linked in the syllabus and instructions of each assignment I’ve posted. Read it. Look at what it emphasizes. Content + Spelling & Grammar are just two dimensions. I also look for Clarity, Organization, Style, Visuals. Many students ignore these factors, but these aren’t arbitrary requirements. They are standard in any good technical document.

  • CS students are often good at describing ‘how’, but not ‘why’: I could make a reasonable argument against every single technical decision you make. There are always tradeoffs. Always. When I write a technical document, critics often come back with the comment “you can’t make that assumption”. So don’t. Provide a rationale. For example: Imagine that you have decided to create a system on iOS. Why?

    • Does it align with your users needs? Platforms and languages are not neutral. For example, if you are designing a medical tablet app, you should be aware that choosing iOS may reduce the accessibility of your app to low income families. You might not like Amazon’s tablets, but know that their low price point opens different opportunities for the impact of your app.

    • Does it align with your client’s needs? Your client and your users may not be the same group of people. Are the platforms you’re choosing accessible to the client? What happens if something goes wrong in the database? Will your client be able to debug it? Probably not. Using Google Sheets as a database sounds silly from a technical standpoint. But it also might make the maintenance and management of the client’s data significantly more accessible. Your technical decisions cannot be divorced from the users.

    • Does it align with your group’s needs? Every technical decision will have a cost. These costs might be in terms of learnability, previous expertise, or development environments. Remember that you are not working by yourself, and the fuse on this project is short. Make decisions that align with the needs of your group.

  • Technical Communication is different than your journals: the tone and formality of these documents should be significantly different. I think and I like are wonderful ways to express your experience, but they do not offer evidence.

    • Instead of: We like the designs of iOS apps so we chose iOS.
    • Write: The design metaphors of iOS align with the expectations and experiences of our users, who are predominately iPhone users.

    Notice the difference! In the first case, you chose iOS just for the hell of it. In the second case, you chose for reasons that are grounded in your project.

  • In general, be a good writer. Norman Ramsey, a CS prof at Tufts University, outlines the following principles in Learn Technical Writing in Two Hours per Week:

    • CORRECTNESS: Write correct English, but know that you have more latitude than your high-school teachers may have given you.
    • CONSISTENT NAMES: refer to each significant character (algorithm, concept, language) using the same word everywhere. Give a significant new character a proper name.
    • SINGULAR: To distinguish one-to-one relationships from n-to-m relationships, refer to each item in the singular, not the plural.
    • SUBJECTS & VERBS: Put your important characters in the subjects, and join each subject to a verb that expresses a significant action.
    • INFORMATION FLOW: In each sentence, move your reader from familiar information to new information.
    • EMPHASIS: For material you want to carry weight or be remembered, use the end of a sentence.
    • COHERENCE: In a coherent passage, choose subjects that refer to a consistent set of related concepts.
    • PARALLEL STRUCTURE: order your text so your reader can easily see how related concepts are different and how they are similar
    • ABSTRACT: In an abstract (or overview), don’t enumerate a list of topics covered; instead, convey the essential information found in your paper.

Writing Checklist

A successful document…

  • Uses terminology—including abbreviations and acronyms—consistently.
  • Avoids ambiguous pronouns (an ‘it’ that is not clear)
  • Uses active voice
  • Avoids long, complex sentences in favor of short, clearer sentences.
  • Uses bullet and numbered lists appropriately
  • Focuses each paragraph on a single topic
  • States key points at the start of each document
  • Identifies a target audience and caters definitions/explanations to that audience
  • Avoids idioms
  • States the document’s scope, goals, and prerequisite knowledge
  • Breaks long topics into appropriate sections
  • Uses captioned, well-designed images to focus reader attention