We all have strengths and weaknesses, and for students of Computer Science, it is often 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. Learn how to get better at 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
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. Your 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. 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 5 on Computing your Future. But for now, let us just acknowledge that hard technical skills like 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.3, 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 12.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.4
- 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.5.
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:
As a species, we’ve been writing stuff down for millenia in order to communicate with each other, see figure 4.6. If you stop to think about it, engineers and scientists spend a lot time communicating in writing. 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 etc
- 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 one or two page summary for management
- reddit.com and hacker news news.ycombinator.com etc
- User documentation, release notes
- 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.7, 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)
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. Prime minister Winston Churchill found that writing helped to keep the “black dog” of his depression under control, see section 3.3.2 and figure 4.8.
So writing can be therapeutic, a powerful tool for developing mindfulness as well as communicating with other people.
Hopefully I’ve convinced you that written communication skills (both as a writer and reader) are important soft skills that engineers often neglect. 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 6.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 :
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 19 for details.
Google occasionally delivers these technical writing courses as free sessions open to the general public. For details, see developers.google.com/tech-writing/announcements for details.
Another technique for improving your written communication is to 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. 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 (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. Read anything, it might be novels, magazines, newspapers, stuff online or any of the books cited in chapter 27. Find a time and place to do this every day and stick to it, see figure 4.10
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 english. 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.11
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.
* PAUSE ⏸️
- 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?
* RESUME ▶️
- 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:
You’ll need both soft and hard skills to compete in the workplace. Don’t underestimate the importance of softer skills, we’ve looked briefly at written communication skills in this chapter but that’s 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.12.
So communicating with other people is a key skill, see figure 4.13. This chapter has looked at written communication, in chapter 10 we will look at spoken communication. Writing your future is coding your future.
This chapter is under construction because I’m using agile book development methods, see figure 4.14.