We all have strengths and weaknesses, and for students of Computer Science, it is sometimes their communication skills that let them down. Other chapters in this guidebook discuss the fundamental communication skills of speaking, listening and reading. This chapter looks at written communication because:
- every engineer is also a writer, and good engineers have good written communication skills
- every scientist is also a writer, and good scientists also have good written communication skills too
Your ability to write clearly isn’t just important when putting together CV’s like in figure 4.1. Your ability to write clearly isn’t just important when composing covering letters or filling in application forms either, it’s a fundamental skill that will help you become a valued employee in the longer term. Learn to write more clearly now and you’ll improve your chances of success later.
Your future is bright, your future needs writing so let’s start writing your future. ✍️
In this chapter you will learn to:
- Recognise the importance of written communication, both as a reader and a writer
- Identify examples of where written communication is crucial in teams of scientists and engineers
- Improve your written communication skills using some simple writing and reading exercises that will improve any job applications you make
Your soft social skills will take a life time to develop and are really hard use. Why? Because soft skills are about communicating with and understanding other people so that you can work together as a team toward a shared goal. Despite their name, soft skills are hard.
There are very few jobs where you work on your own in complete isolation. For example, most software and hardware is designed, built, tested and used by teams of people. Many of these teams are large and have very diverse membership. This means that sooner or later you’re going to have to master the dark arts of working with other people by developing and deploying your softer skills. One of those softer skills you’ll need to continuously develop is written communication.
Communicating with other people and working in teams is inherently difficult because we’re all human. There is good news and bad news…
- THE GOOD NEWS is, people can be diligent, humble, competent, honest, caring and reliable. They can be co-operative, generous, supportive, kind, thoughtful, intelligent, sensitive, understanding, punctual and professional too!
- THE BAD NEWS is, unfortunately people can also be lazy, stupid, ignorant, vain, incompetent, dishonest, unreliable, greedy, egomaniacal, unpredictable and moody. They can be proud, selfish, competitive, lustful, angry, envious, mean, busy, insensitive and thoughtless too. Some will disagree with you, boss you around, betray, exploit, misunderstand and mislead you, deliberately or otherwise. (Goble 2007)
This shouldn’t be news to you but it means communicating with and understanding other people can be hard work, but don’t worry, everyone finds this challenging, it’s not just you! It doesn’t matter if you’re an extrovert or an introvert, communication is a challenge for everybody, and everyone can get better at it too. It’s easy to undervalue the importance of communication because we use it everyday. Just as humanities students are sometimes guilty of being ignorant of science, your average science and engineering student is often guilty of underestimating the importance of the humanities, language and culture, as shown in figure 4.2.
It probably doesn’t help that in the UK, and several other countries, many students specialise early in their education by choosing between:
- EITHER a predominantly science, technology, engineering, and mathematics (STEM) pathway
- OR an “artier” and allegedly more “creative” humanities pathway (Cole 2017)
Are C.P. Snow’s two (seperate) cultures of humanities and science still living in seperate houses like an estranged and bickering couple? Would he judge the gaps between the two cultures to have closed or been widened in the sixty years since he described them? (Snow 1959) This is debateable but in the worst case scenario, two cultures in society produces:
- science and engineering graduates who are technically strong but have weaker communication skills, both written and spoken, combined with cultural ignorance, political indifference, general illiteracy and other inhumanities
- humanities graduates who are articulate, well read, vocal, persuasive and write clearly but sometimes lack technical skills. In extreme cases, they can be scientificially and mathematically illiterate
Are you in the first category? This chapter takes a look at the softer skill of written communication and techniques you can use to improve your writing. Whatever mood your readers are in, they’ll find it a lot easier to work with you when you can express yourself clearly in writing.
Studying computer science gives you an awesome superpower. We will look at some of the reasons why in chapter 7 on Computing your Future. But for now, let us just acknowledge that hard technical skills in computing are highly sought after and valuable, both commercially and otherwise.
Your computational superpower is less powerful if it isn’t complemented by a broad range of softer skills. Typically, these skills are not closely examined in most computer science degrees, for example by repeated assessment. There’s an awful lot of technical computing curriculum that tends to have a higher priority over soft skills. It’s not that soft skills aren’t important but that they can be hard to quantify.
For example, if I want to know how good you are at understanding the syntax and semantics of a programming language like Python, there are tried and tested techniques for measuring this. However, if I want to know how good you are at using your communication skills to work in a team of engineers to negotiate, lead, resolve conflicts, persuade others, show empathy etc that’s much harder to measure accurately. What technical degrees tend to measure is technical skills because softer skills, shown in figure 4.4, are much harder to assess by examination and coursework.
This is one of the many reasons that you are much more than your grades, see figure 18.3.
Let’s look at some of low-level communication skills (
I/O) that they are built on.
In terms of input and output, your fundamental communication skills are listening, speaking, reading and writing words in natural languages shown in table 4.1. These are the “assembly languages” of human communication. This might sound blindingly obvious, but these skills are often under-estimated or undervalued by engineers and scientists, especially undergraduates. Alongside verbal and written communication, there’s also nonverbal language, or body language such as eye contact, gestures and facial expressions.
|Written natural language||Reading||Writing|
|Spoken natural language||Listening||Speaking|
|Nonverbal language||Observing other people||Being observed by others|
Some people leave plenty of room for improvement when it comes to the communication skills outlined in table 4.1. Think of:
- the stereotypical mad scientist, clad in a white coat, unable to explain the complexities of their research to people inside their lab, let alone outside of it, see figure 4.5
- the nerdy software engineer stereotype who prefers the company of computers to people
Yes, these are lazy tropes and unhelpful stereotypes, but they express public perception of scientists and engineers as poor communicators. Don’t perpetuate the stereotype by being a bad communicator.
The art of communication is a huge subject which extends far beyond the scope of this guidebook. So for the rest of this chapter, we’ll focus on your superpower of written communication. The pen (and keyboard) are mightier than the sword, see figure 4.6.
Written communication skills are important because:
- Good writing and reading are crucial in applications for employment and further study. From writing CV’s, covering letters, completing application forms and reading job specifications, and employer (or course) information, your ability to read and write in natural languages is crucial to coding your future.
- Writing often gets neglected: Written communication skills (both reading and writing) are sometimes sidelined in science and engineering degrees. This is particularly true in the “hard sciences”. For example, communicating and solving problems using code or mathematics are usually the dominant forms of assessment in computer science courses. That’s understandable given the subject, but tends to push natural languages (like english) to the sidelines.
- Good engineers are also good writers Many engineers (and scientists) could significantly improve their written communication skills. Software engineers are notoriously bad at writing, see for example Why Computer Science Students Need Language, (Beaubouef 2003) Scientists Must Write (Barrass 2002) and The Real Reason Silicon Valley Coders Write Bad Software, (Meisler 2012) just three examples amongst many others making exactly the same point. Employers like Google provide training (and a whole career path) for technical writers, see developers.google.com/tech-writing. I’m glad they exist, but these careers and courses wouldn’t be needed if software engineers were better at documenting, explaining and communicating with other human beings in the first place!
Writing good english is like writing good code. Some of the skills you already have in coding can be transferred to written communication. Just like a good
methodin code should be well-defined with a clear purpose, your writing should also be clear and coherent. Well structured writing is a lot like well architected software too, with a clear separation of concerns (SoC)
- It is relatively easy to improve your written communication skills, simply by reading and writing more. Reading and writing deliberately every day, will significantly improve these skills. See the rest of this chapter for some simple exercises to get started with and:
We have been writing stuff down for millenia in order to communicate with each other. If you stop to think about it, engineers and scientists spend a lot time communicating in writing, see figure 4.7. As well as engineering
code, they also spend a significant amount of time engineering messages in natural languages like english.
Consider the following:
- email and instant messaging, Slack, Microsoft Teams, Discord, Zoom etc
- Posting on social media: LinkedIn, Facebook, WhatsApp, Twitter, blogs, medium.com, substack.com and whatever platform is fashionable this week.
- bug reports and messages in issue trackers like Jira, BugZilla, Trello and version control systems like Github and Gitlab etc
- ‘How to’ and cookbook style articles and books
- API reference material
- in-code documentation
# comments in code
- Self-documenting code that describes itself
- Executable specifications in test suites like cucumber.io
- Laboratory manuals and laboratory notebooks
- The \(x\) page summary for management, where \(x\) might be equal to \(1\), or \(2\) or even \(6\) if you work at Amazon (Freeman 2020; Bezos 2021)
- reddit.com and hacker news news.ycombinator.com etc
- User documentation, release notes and the like
- Case studies of software use
- Frequently Asked Questions (FAQ)
- Personal websites
YourPersonalDomain.comif you have one
- Questions and answers on forums like stackoverflow.com
- Commit messages in version control systems like git and mercurial etc
- Architecture documentation and design specifications
- Literate programming natural language descriptions of computational logic (Knuth 1984)
- Jupyter.org notebooks, code and natural language mixed together, as do many other systems like, quarto.org and bookdown.org
What do they all have in common? They’re all written in natural languages like the English language, but without them, the software or hardware they describe and discuss would be useless. Using written (and spoken) natural language is a key social skill and a communication skill. You might be using your language to influence, persuade, convince or argue with members of your team. So it is important that you do it to the best of your abilities. Computer Scientist Luis von Ahn, shown in figure 4.8, is the creator of duolingo.com. Luis regrets that he didn’t spend any effort developing his social skills early in his career. Instead, like many computer scientists he focussed his effort on his mathematical and technical skills instead. (Shaw 2021)
Making software isn’t all about what you can do as an individual but rather how you communicate with and contribute to your team. It’s easy to get carried away with your ego. Remember that most jobs require lots of softer people skills and collaboration, written communication is a huge part of that, alongside spoken communication see for example The Myth of the Genius Programmer. (Fitzpatrick and Collins-Sussman 2009)
Writing has multiple uses, or to use a programming analogy, it is an overloaded function. We need to examine some of these different functions, because they are easily overlooked and taken for granted, especially by engineers and scientists. We read, write and rewrite everyday without stopping to give it much thought. If you don’t like writing, you need to learn to love it because it’s actually your friend. Not just any friend, but your Best Friend Forever (BFF), see figure 4.9.
So let’s expand on each of the reasons in figure 4.9 why writing is your new BFF:
Writing is communication, see figure 4.10. Well Duh! I’m stating the obvious, because you will sometimes hear software engineers talking disparagingly about writing the (sigh)
Engineers may sometimes tell you that writing about their software or hardware can be a chore. If they bother to write about their software at all, they often do it at the end, if there is time and there’s no more features to be added or bugs to be removed. This might go some way to explaining why software and hardware documentation can be so bad because:
- It is probably written as an afterthought or in a hurry
- It might not be authored by the person who actually designed or built the software
- The documentation may be describing complex processes or very abstract concepts
- It may have been mangled with the original meaning lost in translation to a different (natural) language
- The author may lack empathy with their readers8
A good example of this is the documentation for the distributed version control system git. While
git is a powerful tool that is worth spending time learning about, like most powerful tools, it is also quite complicated. Some of the documentation on git is very good (Chacon and Straub 2014) but other parts of it tend towards impenetrable jargon-ridden nonsense. Take this example selected by Santiago Perez De Rosso from the documentation describing a command known as
git-wave-stash (Rosso 2017)
wave all staged stashes next to various cherry-picked non-applied applied trees
Can you work out what that actually means? Me neither. No doubt, you can think of many other examples where you’ve been reading documentation and thought
WTF? This is just one example from many that shows why good writing is crucial for communication.
Badly written text like the example above, fails to communicate with the reader. We’ve all been on the receiving end of badly written prose, especially when it comes to software and hardware documentation. When it is done well, writing quickly communicates what readers actually need to understand.
What were you doing on the March 6th 2013? You probably don’t know and I’ll bet you would probably struggle to find out. I don’t know what I was doing on March 6th 2013 either because I have no written records for that day. If I was an obsessive–compulsive diarist (OCD), I’d have a written record of what happened to me on that day. But I’m not, so I don’t. The point here is that, writing doesn’t just communicate it also records what has happened, see figure 4.11.
If it might be important, it is probably worth writing down. Even things you think are trivial are still worth writing down as they might turn out to be important later:
- Minutes from a meeting
- Lecture notes you’ve written
- A bug you’ve been working on including how you fixed it
So besides communicating, writing records what happened. If you don’t write it down, it might just disappear forever without trace. The audience you’ll be communicating with isn’t just other people, it might be your future self. That future self might really need to know how you fixed that bug, and it could save you hours of re-figuring out how to solve a problem you’ve already solved.
Have you ever felt moved or influenced by a piece of writing? Have you ever read something that motivated or influenced you to do something? Of course you have. If, as Harry Truman supposed, leaders are readers then writers are too. (Truman 1955)
Let’s take the United States Declaration of Independence shown in figure 4.12. We’re still talking (and singing) about it more than 200 years after it was written. (Jefferson et al. 1776; Miranda 2015) That’s not just because it was influential, it’s because it was written down. The seemingly mundane and lo-tech but hi-fi act of humble writing. The declaration is “just” words, written down on a piece of paper, but words that changed the course of history.
You say you want a revolution? Well, you know, we all want to change the world. (Lennon and McCartney 1968) Whatever kind of revolution you want to start or join, you’ll stand a much better chance of making it happen, if you write down your ideas in a way that people can clearly understand. This might include mini-revolutions such as:
- Getting a job interview, by crafting a persuasive covering letter and compellng CV
- Encouraging people to join
projectsyou’ve started, see section 8.6.4
- Negotiating terms and conditions of a contract of employment, you might start by email
- Getting someone to invest in your startup or offer you some freelance or contract work
- … and so on
So writing well won’t just help you communicate and record, it will help you to become a more successful leader too by specifying exactly what you mean so you can convince other people to follow your lead.
Your brain tends to work much more quickly than your fingers can type or your hands can write. Your brain will often work much faster than you can speak as well. Writing can slow that process down to something more manageable and concrete, by focussing your thoughts on a given topic or problem, see figure 4.13.
Writing forces you to say more exactly what you are thinking. Slowly. Whereas thoughts can be fast, vague and slippery, writing needs to be much more precise and accurate. The author and playwright Hanif Kureishi writes to find out what he thinks, see figure 4.14. Working out what you think takes time, one of reasons writing can be challenging or lead to the dreaded writer’s block. (Orwell 1946)
Ever got stuck on a difficult problem? Ever tried writing that problem down or articulating the details to a rubber duck? There’s something about writing a problem down or articulating the issue to another person. Even a rubber duck will do, see figure 4.15. So writing can be a useful technique for solving problems, even if nobody else ever reads what you’ve written or heard what you’ve spoken.
By the time you’ve written that stackoverflow.com question about a techincal problem you are struggling to solve, your brain may have figured it out. This is much more likely to happen if you articulate the problem in words, either written down or spoken, to a rubber duck.
When you are writing a CV, résumé or a covering letter, the product of your writing is the most important output. But sometimes, it is the process of writing that matters more than the product, see figure 4.16.
Here are some examples where the process of writing can be more important than its product:
- Taking notes helps you concentrate on what a speaker is saying
- Writing a reflection which forces you to analyse on what has happened and what you’ll do next, see section 17.6. Cognitive psychologists call this metacognition, thinking about thinking
- Writing down a problem helps you to solve it, as described in section 4.5.5
So writing is important as a process as well as a product. That process might include slowing down (section 4.5.4), speeding up (section 4.5.8) or both. Either way, writing forces you to be clear and focus, it is a process for working, not just the product (output) of working. When you write a dissertation or thesis for your bachelors or masters degree the process of writing is as important as the product. The computer scientist Simon Peyton Jones outlines how recognising this can help you to write a better dissertation or thesis in figure 4.17.
If you’re using a machine like ChatGPT to help you write (see section 4.6.3), you’ll be bypassing some of the valuable process of writing that Peyton talks about. (S. P. Jones 2016) Yes, writing can sometimes be painful and slow, but its one of the best ways to learn. If you’re looking to improve your academic writing (essays, theses, dissertations etc), you will find www.phrasebank.manchester.ac.uk useful. (Morley 2023)
Besides being a tool for communication, writing can be therapeutic for the writer too. The simple act of writing can help you tackle mental health issues discussed in chapter 3. You might think it tragic somebody writing a diary that nobody reads, but actually, that’s not the only point of the diary. The metacognition we described in section 4.5.6 is a valuable exercise in its own right. You could think of writing like a therapists couch shown in figure 4.18. (Mugerwa and Holden 2012)
As well as slowing your brain down discussed in section 4.5.4, writing can also speed it up by wicking ideas like a candle wick does for candle wax. Without the wick, the candle wax can’t undergo the chemical reaction that transforms it into carbon dioxide and water. As the software engineer Paul Graham puts it:
“If I can’t write things down, worrying about remembering one idea gets in the way of having the next. Pen and paper wick ideas”
“I think it’s far more important to write well than most people realise. Writing doesn’t just communicate ideas; it generates them. If you’re bad at writing and don’t like to do it, you’ll miss out on most of the ideas writing would have generated”
So writing down whatever is in your head will often help you refine your ideas and generate even more new ones as shown in figure 4.20.
Hopefully I’ve convinced you that written communication skills (both as a writer and reader) are important soft skills that scientists and engineers often neglect. Writing performs multiple functions, so how can you improve?
Dogfooding is a simple technique for testing your own writing. Let’s say you’ve just written a personal statement or covering letter (see section 8.10). It’s natural to read it over in your head to check for errors, before you send it. However, reading it aloud will pick up errors you may not have spotted by reading silently. Your ears and tongue will pick up on awkward phrases and sentences that your eyes didn’t spot. There’s something about articulating words out loud that flushes out errors you don’t pick up when you read them in your head. Dogfooding is a tried and tested technique. It also means you’re ready to vocalise those answers in an interview.
You might want to choose carefully where you do this as it might look a bit strange, but it works well. If you talk into a mobile phone while looking at a piece of paper, people won’t notice you’re talking to yourself. But you’ll probably need some privacy as the stuff you’re talking about is likely to be personal. Alternatively, find a critical friend who you can read out loud to. You can also use a screen reader, for example :
A screen reader will often reveal mistakes you haven’t spotted by reading your text silently.
Google have developed some excellent written communication courses for software engineers, and those looking to become technical writers:
- Technical Writing One: Technical Writing Fundamentals for Engineers developers.google.com/tech-writing/one
- Technical Writing Two: Intermediate Technical Writing for Engineers developers.google.com/tech-writing/two
You might also be interested in the follow on courses:
- Tech Writing for Accessibility developers.google.com/tech-writing/accessibility
- Writing Helpful Error Messages developers.google.com/tech-writing/error-messages
The first two tech writing courses run as part of the second year course COMP2CARS at the University of Manchester, see chapter 14 for details.
Google occasionally delivers these technical writing courses as free sessions open to the general public, see figure 4.22. For details, see developers.google.com/tech-writing/announcements for details.
There is no shortage of software to help you write better, beyond the basic spelling and grammar checkers described in section 8.7.8. The more sophisticated tools are often powered by Artificial Intelligence (AI). (Hogarth 2023) Some of these tools are tailored to improving academic writing while others can be used to improve your written job applications. An incomplete selection of tools you could experiment with, if you haven’t already, is shown below:
- angryreviewer.com by Roman Anufriev is a bit blunt but will give you honest feedback on your writing
- ChatGPT (see figure 4.23), Bing and Bard (Mehdi 2023; Pichai 2023)
- DrivelDefence part of the Plain English Campaign, see also The Complete Plain Words (Gowers and Gowers 2015)
- ecree.com a writing tutor
- grammarly.com reviews the spelling, grammar, punctuation and clarity of your writing
- jasper.ai AI powered content generator
- paperpal.com for academic writing
- quillbot.com tool for paraphrasing
- scholarcy.com AI-powered article summariser
- toowrite helps you to write a paper
- wordtune.com summarises long documents
- writefull.com helps you to write, paraphrase and edit
All of these tools will be biased by whatever data they’ve been trained on and encode some of the prejudices of the engineers that wrote their algorithms. You need to be careful about plagirism (if it is academic work) and writing generic job applications that are de-personalised and de-humanised. Employers will be able to spot these a mile off.
Another problem with using writing machines to help you communicate is that while the more sophisticated software might help overcome some of the dreaded writer’s block, they bypass the important process of writing discussed in section 4.5.6. Writing about something is one of the best ways to learn about it, and sometimes the best time to write is when you’re trying to figure out the subject for yourself. If you wait until you’re an expert, it will be too late to start. If you get a machine like ChatGPT to write for you, you won’t identify gaps in your knowledge and develop the expertise to fill them.
So viewing writing as just another kind of
output, overlooks a lot of the value of writing in the first place.
Despite their limitations, and the fact that we’re still trying to figure out what their long term impacts will be, writing machines may help you to communicate more clearly and quickly. (Pratschke 2023; Stokel-Walker and Noorden 2023; Hutson 2021)
Another technique for improving your written communication is to deliberately write something every day, that might be a personal diary that only you read, or it could be something more public like blog. Schedule a time every day, say 15 to 30 minutes when you will do this without fail. Sometimes this will be easy, other times it will be hard. What’s important is that you write something, see figure 8.5. That writing could take several forms:
- public web log or blog
- gratitude journal see section 3.4
- private diary or personal laboratory notebook
- morning pages, a unedited stream of conciousness that can help you become more creative 8.5 (Cameron 1992; Burkeman 2014)
- bullet journal. Some people swear by it, see bulletjournal.com
The technique of 30 minutes per day can be a very effective way of getting things done, incrementally over time. In my experience it works for lots of things besides writing including getting exercise (discussed in chapter 3) to gardening. (Leendertz 2006)
Reading other people’s code will improve your software engineering skills. Likewise, reading other peoples writing will improve your natural language engineering skills. Leaders are readers! Read anything, it might be novels, magazines, newspapers, stuff online or any of the books cited in chapter 33. Find a time and place to do this every day and stick to it, see figure 4.24
You don’t get good at communicating with computers (coding) by just writing lots of code. You also need to read other people’s code too and be able to understand and modify it. Likewise, you don’t get good at communicating with people by just writing stuff in natural languages like the English language. You need to read stuff too. Books, manuals, software documentation, articles, use cases, novels, poetry, plays, magazines, newspapers etc. Reading this stuff will help you learn and you’ll improve your written communication skills too. So Read The Friendly Manual. RTFM. Read THIS Friendly Manual and the stuff it cites, see figure 4.25
Let’s pause here. Insert a breakpoint in your
code and slowly step through it so we can examine the current values of your variables and parameters.
- Which of the communication skills in table 4.1 are your strongest?
- Which of the communication skills in table 4.1 are your weakest?
- What activities could you do to improve your weaker communication skills?
- How can you use writing machines to improve your written communication?
- Write an article or blog post about something you care about, find a suitable venue for publication
- Take a course from outside computer science, where the main form of assessment is written essays or dissertations. Humanities departments are a good place to start. This will improve your written communication skills
- Not been reading many books lately? Pick a book to read just because its interesting, rather than because you have to.
Too long, didn’t read (TL;DR)? Here’s a summary:
Your future is bright, your future needs writing. Writing your future will help you design your future. Designing your future will help you to start coding your future.
You’ll need both soft and hard skills to compete in the workplace. Are you underestimating the importance of softer skills? We’ve looked briefly at the softer written communication skills in this chapter and some simple techniques for improving them. You can go a step further by enrolling on some humanities courses where you’ll develop your these skills even more.
Written communication skills are only the tip of the soft skills iceberg. Teamwork, negotiation, conflict resolution, public speaking, motivating others and leadership are also important soft skills too. How can you develop these skills while at University? How can you demonstrate to potential employers that you have these skills? Your technical skills are of limited use without people skills, to allow you to work with others see figure 4.26.
So communicating with other people is a key skill, see figure 4.27. This chapter has looked at written communication, and its importance in persuading people to invite you to a job interview, in chapter 13 we will look at the closely related skill of spoken communication.
In the next part, chapter 5 you will reflect on what experience you have and how you can articulate that to potential employers, with written and spoken communication.
This chapter is under construction because I’m using agile book development methods, see figure 4.28.