4 Writing your future
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. ✍️
4.1 What you will learn
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
4.2 Writing as a soft social skill
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 for scientists, technologists, engineers and mathematicians to undervalue the importance of communication because we use it everyday. Just as humanities students are sometimes guilty of being ignorant of science, you’re average science 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 have weaker communication skills, both written and spoken, combined with cultural ignorance or illiteracy
- humanities graduates who are articulate, well read, 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.
4.3 Computing is your superpower!
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 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 12.3.
Let’s look at some of low-level communication skills (
I/O) that they are built on.
4.4 Communication I/0
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.
4.4.1 The pen is mightier than the sword
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:
4.4.2 Natural language engineering
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)
4.5 Writing your future
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 and write 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:
4.5.1 Writing as communication
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.
4.5.2 Writing as recording
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.
4.5.3 Writing as leadership
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.
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 6.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.
4.5.4 Writing as slowing down
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)
4.5.5 Writing as problem solving
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.
4.5.6 Writing as a process, not just a product
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 11.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.
4.5.7 Writing as therapy
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)
The UK 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.19.
So writing can be therapeutic, a powerful tool for developing mindfulness as well as communicating with other people.
4.5.8 Writing as speeding up
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.
4.6 Improving your writing
Hopefully I’ve convinced you that written communication skills (both as a writer and reader) are important soft skills that engineers often neglect. Writing performs multiple functions, so how can you improve?
Many employers test their products and services by trialling them on their own employees, this is known as eating your own dogfood shown in figure 4.21. Tasty, tasty dogfood. 🐶
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 :
- Microsoft Teams has an immersive reader
- Android devices have TalkBack
- Apple devices have VoiceOver
A screen reader will often reveal mistakes you haven’t spotted by reading your text silently.
4.6.2 Try Google’s Tech Writing courses
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, see figure 4.22. For details, see developers.google.com/tech-writing/announcements for details.
4.6.3 Writing machines
There is no shortage of software to help you write better, beyond the basic spelling and grammar checkers described in section 6.7.7. The more sophisticated tools are often powered by Artificial Intelligence (AI). 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 its a bit blunt but will give you honest feedback on your writing
- ChatGPT (see figure 4.23), Bing and Bard (Mehdi 2023; Pichai 2023)
- coauthor.stanford.edu a dataset built from human-AI collaborative writing (Lee, Liang, and Yang 2022)
- 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
- 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.
Despite their limitations, and the fact that we’re still trying to figure out what their long term impacts will be, they can all help you to communicate more clearly and quickly. (Pratschke 2023; Stokel-Walker and Noorden 2023; Hutson 2021)
4.6.4 Deliberate daily writing
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)
4.6.5 Deliberate daily reading
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.24
4.6.6 Reading the friendly manual
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.
* 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?
- How can you use writing machines to improve your written communication?
* RESUME ▶️
4.7.1 Coding challenges
- 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.
4.8 Summarising your soft skills
Too long, didn’t read (TL;DR)? Here’s a summary:
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, 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.28.