4 Writing your future

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

Figure 4.1: I often ask students about their motivation for studying Computer Science at University, you can hear some of their answers in chapter 21. One of my tutees⁷ once told me they chose to study computing because (quote): I didn’t like all the arty-farty humanities subjects at school. Literature, history, languages, culture, all those essays we had to write and debates about politics. Bla bla bla. I hated that stuff! (unquote) My tutee preferred the precision and accuracy of mathematics and science. Fair enough, but while you can run from written and spoken communication, but you can’t hide from it. Writing a CV, covering letter or filling in an application form is just the tip of the natural language iceberg, section 4.4.2 outlines the some of the rest. This chapter looks at some simple techniques for improving and investing in your written communication skills. Avoidance sketch by Visual Thinkery is licensed under CC-BY-ND

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. ✍️

4.1 What you will learn

In this chapter you will learn to:

1. Recognise the importance of written communication, both as a reader and a writer
2. Identify examples of where written communication is crucial in teams of scientists and engineers
3. Improve your written communication skills using some simple writing and reading exercises that will improve any job applications you make

4.2 Writing as a soft social skill

Your soft social skills will take a life time to develop and can be 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 misleading name, soft skills can be hard to use and are often underestimated or overlooked.

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.

Figure 4.2: Many Computer Scientists are steeped in the culture of Science, Technology, Engineering and Mathematics (STEM), seperated by a gulf of mutual incomprehension from their counterparts in the humanities. C.P. Snow argued that this gulf between the two cultures was bad for both sides as it handicaps our abilities to solve major global problems. (Snow 1959) Fair use image of C. P. Snow on the cover of The Two Cultures via Wikimedia Commons w.wiki/6Rhv adapted using the Wikipedia App

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:

1. 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
2. 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.

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 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.

Figure 4.3: Computing is a superpower that Gods like Hermes and mortal heroes like Achilles would probably have envied. (Fry 2018, 2017) As a technical or hard skill, computing is a crucial weapon in your armoury but what are your weaker skills? What is your Achilles’ heel? For some scientists and engineers, their weakness is their soft skills, such as communication. Writing, reading, speaking and listening to communicate with team members can be a weaker skill for many technical people. This chapter looks at what you can do to improve these skills and convince employers that you are rounded individual with a healthy balance of soft and hard skills. Achilles heel to superpower by Visual Thinkery is licensed under CC-BY-ND

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 19.3.

Figure 4.4: Hard skills and soft skills aren’t much use without each other. You will need both to survive and thrive but most science and engineering education focuses on your hard skills, not your soft skills. Why? Because hard skills are often much easier to measure. Hard and soft skills sketch by Visual Thinkery is licensed under CC-BY-ND

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.

Table 4.1: The inputs and outputs of the fundamental assembly languages of human communication

	Input	Output
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.

Figure 4.5: Are you mad, bad and dangerous to know? You’ll be familiar with the mad scientist stereotype: perceived as an evil genius owing to a combination of unsettling personality traits and the unabashedly ambitious, taboo or hubristic nature of their experiments. Besides their supposed insanity, another reason mad scientists (and engineers) are perceived badly, is their poor communication skills. Maybe if they could communicate better the public might understand and trust them more? Don’t perpetuate the stereotype by being a poor communicator, there are too many of those already! CC BY-SA cartoon of a mad scientist by J.J. on Wikimedia Commons w.wiki/5JeU adapted using the Wikipedia App

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.

Figure 4.6: Do you need more weaponry in your life? Besides computing, you should arm yourself with communication superpowers. It’s in your own selfish interests to continuously develop your written communication skills because the pen is mightier than the sword. Public domain image of a drawing of Cardinal Richelieu by Henry Alexander Ogden via Wikimedia Commons w.wiki/3WHg adapted using the Wikipedia app

Written communication skills are important because:

1. 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.
2. 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.
3. 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!
4. 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 function, class or method in 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)
5. 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:
   • chapter 8 on Debugging your future
   • chapter 9 on Hacking your future for details.

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.

Figure 4.7: As a student you might be focussed on the tip of the natural language iceberg most visible at University: CV’s, covering letters and longer project reports for your coursework assignments. These are just the tip of the iceberg, underneath is a tonne of other communication you’ll need to write (and read) to be a successful engineer or scientist: emails, bug reports, FAQs, case studies, white-papers, design specifications, in-code documentation, marketing, mainstream news and social media. The list goes on and on. So, there is a lot more to the natural language iceberg than meets the eye. Natural language iceberg by Visual Thinkery is licensed under CC-BY-ND

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.com if 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)

Figure 4.8: Luis von Ahn is the Chief Executive Officer (CEO) of duolingo.com. Since 2012, the duolingo app has been downloaded 500 million times. Luis wishes he’d concentrated on developing his social skills earlier his career. Are you developing your hard technical skills at the expense of your softer social skills? Portrait of Luis von Ahn by EneasMx on Wikimedia commons w.wiki/4VPU adapted using the Wikipedia app

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. (B. Fitzpatrick and Collins-Sussman 2009)

4.5 Rewriting your future

Writing has multiple uses, if it were a function or a method, it would be an overloaded one performing different tasks. We need to examine these tasks, because they are easily overlooked and taken for granted, especially by engineers and scientists. We read, write and rewrite stuff 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.

Figure 4.9: Eight reasons why writing is your new Best Friend Forever (BFF): Communicating, see section 4.5.1. Recording, what happened see section 4.5.2. Leadership: persuading other people to do something, see section 4.5.3. Slowing down: when your brain works too fast, see section 4.5.4. Problem solving: when your brain can’t solve a problem (yet), see section 4.5.5. Process not product, reflection and metacoginition, see section 4.5.6. Therapy: when your brain isn’t helping because it makes you unhappy, anxious or depressed, section 4.5.7. Speeding up: when your brain too slowly, see section 4.5.8. B.F.F. by Visual Thinkery is licensed under CC-BY-ND

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 communication. For example, you might hear them complaining about writing the (sigh) documentation or having to explain things to (yikes) customers or stakeholders.

Figure 4.10: Your writing will communicate better if you invest more time in rewriting to make it clearer. Tin can telephone sketch by Visual Thinkery is licensed under CC-BY-ND

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 readers⁸

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

— Anon (Rosso and Jackson 2016)

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 details 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.

Figure 4.11: If you don’t write it down there will be no record that it actually happened, whatever it was. While it is difficult to know in advance exactly what you might need to record, the safest option is to write as much of it as you can anyway, just in case. Old school reel to reel tape recorder sketch by Visual Thinkery is licensed under CC-BY-ND

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. If, as Harry Truman supposed, leaders are readers then writers are too. (Truman 1955)

Figure 4.12: We hold these truths to be self-evident, that all men (and women) are created equal… Just words written down on a piece of paper, but words that made people follow. (Jefferson et al. 1776) Declaration sketch by Visual Thinkery is licensed under CC-BY-ND

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 compelling CV
• Encouraging people to join PROJECTS you’ve started, see section 8.6.5
• 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.

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 your thinking process down to something more manageable, by focussing your thoughts on a given topic or problem, see figure 4.13.

Figure 4.13: Is your brain working too quickly for its own good? Writing can help to slow it down and take it one step at a time. Slowing down sketch by Visual Thinkery is licensed under CC-BY-ND

Writing forces you to say 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)

Figure 4.14: Like many authors, the playwright Hanif Kureishi writes to find out what he thinks. (Lawley 1996) Whatever you are writing, you’ll have a much better understanding of what you are actually thinking after you’ve tried to write it down. Writing isn’t just an important product, it’s a crucial process too. CC BY-SA portrait of Hanif Kureishi speaking at Emory University in 2008 by Brett Weinstein on Wikimedia Commons w.wiki/6SKv adapted using the Wikipedia App

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.

Figure 4.15: Ever tried explaining that troublesome bug to a rubber duck? Welcome to rubber duck debugging, a tried and tested technique for problem solving, either through written or spoken communication with an inanimate object. Rubber duck sketch by Visual Thinkery is licensed under CC-BY-ND

By the time you’ve written that difficult problem down, your brain may have figured it out. For example, as you’re writing that stackoverflow.com question, your brain will sometimes magically solve it. This is much more likely to happen if you articulate the problem in words, either written down, spoken to a person or a rubber duck like the one shown in figure 4.16

Figure 4.16: In software engineering, rubber duck debugging is a method of debugging code by articulating a problem in spoken or written natural language. Some people call it deducktive reasoning. CC BY-SA rubber duck picture by Tom Morris on Wikimedia Commons w.wiki/4QHW adpated using the Wikipedia App 🦆

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 and reflecting that matters more than the product (output), see figure 4.17.

Figure 4.17: Sometimes the process of writing (the blue bit) is more important than the product of writing (the red output). Process sketch by Visual Thinkery is licensed under CC-BY-ND

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 18.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.18.

Figure 4.18: Computer scientist Simon Peyton Jones explains how to write a better dissertation or thesis by writing early and often, rather than waiting to write it all at the end. He’s talking about writing papers here, but what he says applies to writing a thesis too: Writing helps you be clear by crystallizing what you understand. It’s important as a process as well as a product. You can also watch the full 57 minute video embedded in this figure at youtu.be/VK51E3gHENc (S. P. Jones 2016)

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 Simon 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 2024)

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.19. (Mugerwa and Holden 2012)

Figure 4.19: Dear Diary …: The therapeutic effects of writing are well documented, even if that writing isnt actually read by anyone. Therapy sketch by Visual Thinkery is licensed under CC-BY-ND

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.20.

Figure 4.20: Winston Churchill managed to regulate his depression by writing. If you are affected by anxiety or depression, you may find that private forms of writing like those described in section 4.6.4 will help to improve your mental health. Public domain portrait of Winston Churchill by Yousuf Karsh on Wikimedia Commons w.wiki/4aJk

So writing can be therapeutic, a powerful tool for developing mindfulness as well as communicating with other people. (Chiatrist 2023)

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”

— Paul Graham (Graham 2006)

and also

“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”

— Paul Graham (Graham 2005b)

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.21.

Figure 4.21: Want to have more ideas? Want to have better ideas? Just writing them down can help you refine your ideas as well as generating novel ones too. Thinking sketch by Visual Thinkery is licensed under CC-BY-ND

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 scientists and engineers often neglect. Writing performs multiple functions, so how can you improve?

4.6.1 Dogfooding

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.22. Tasty, tasty dogfood. 🐶

Figure 4.22: Reading your own writing (aloud) is like eating your own dog food. It’s a simple and proven technique for improving your written communication in job applications such as covering letters, personal statements and the like. Dogfooding by Visual Thinkery is licensed under CC-BY-ND)

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.12). 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:

1. Technical Writing One: Technical Writing Fundamentals for Engineers developers.google.com/tech-writing/one
2. Technical Writing Two: Intermediate Technical Writing for Engineers developers.google.com/tech-writing/two

Figure 4.23: While engineers can write code, they often struggle to communicate effectively in written natural languages like English. Technical writing courses like the free ones held by Google can help you become a better communicator. CC BY-SA picture of the Googleplex in California by The Pancake of Heaven via Wikimedia Commons w.wiki/3X4t adapted using the Wikipedia app

You might also be interested in the follow on courses:

1. Tech Writing for Accessibility developers.google.com/tech-writing/accessibility
2. 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 15 for details.

Google occasionally delivers these technical writing courses as free sessions open to the general public, see figure 4.23. 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 8.7.8. The more sophisticated tools are often powered by Artificial Intelligence (AI), see figure 4.24. (Hogarth 2023)

Figure 4.24: Chat Generative Pre-trained Transformer (ChatGPT) is a chatbot developed by OpenAI.com. (Altman 2023) Based on a large language model (LLM) it enables users to generate text of to their desired length, format, style and language. ChatGPT is one of many writing machines or robo-writers that you can potentially use as an assistant to help you communicate more quickly and clearly. Note that despite the name, the language model that ChatGPT is built on is NOT openly available. (Dis et al. 2023) OpenAI logo from Wikimedia Commons w.wiki/6Lat adapted using the Wikipedia App 🤖

Some of AI powered writing 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.24), 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
• tldrthis.com Too Long; Didn’t Read? TLDRthis will summarise it for you
• scholarcy.com AI-powered article summariser
• tldrthis.com Tool Long Didn’t Read (TLDR) this? Summarises text for you
• 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. (Advisor 2023b; Christian 2023)

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)

4.6.4 Writers are fighters!

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)

4.6.5 Leaders are readers

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 35. Find a time and place to do this every day and stick to it, see figure 4.25

Figure 4.25: Reading allows you to learn from other people’s hard won experience whilst also improving your own written communication skills. Just like you improve your coding skills by reading and writing code, you will improve your written communication skills by reading and writing in natural languages. The motivation for reading by Visual Thinkery is licenced under CC-BY-ND with help from Michael Rosen

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.26

Figure 4.26: Read The Friendly Manual (RTFM), some of it you will love, some of it you won’t. Either way reading will help you develop valuable skills and knowledge. Read The Friendly Manual by Visual Thinkery is licenced under CC-BY-ND

4.7 Breakpoints

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 written skills

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.27.

Figure 4.27: Unless you want to be a lighthouse keeper on a remote island, there are very few jobs where you don’t have to work as part of a team with other people. If you were hoping to carry on working independently from other people, sorry to break the bad news! In the longer term, you will benefit from constantly improving your softer skills and providing evidence of them to potential employers. Written communication is just one of those softer skills. Other people sketch by Visual Thinkery is licensed under CC-BY-ND

So communicating with other people is a key skill. Writing more will help improve your written communication skills, we looked at some simple techniques for doing this in section 4.6. Just write, see figure 4.28.

Figure 4.28: The author Charlotte Brontë wrote the classic gothic novel Jane Eyre. (Brontë 1847) She just couldn’t help it: “I’m just going to write because I cannot help it”. Just write, see section 4.6.4 for some starting points. Most computer scientists don’t write or read enough material in natural languages like English, especially when compared to their counterparts in the humanities. Writing and reading more will make you a better communicator. Quotation via bronte.org.uk, public domain image of a chalked portrait of Charlotte Brontë by George Richmond via Wikimedia Commons w.wiki/9idq adapted using the Wikipedia App ✍️

This chapter has investigated the art of written communication, and discussed its importance in persuading people to invite you to job interviews, amongst other things. In chapter 13 we will look at the closely related communication skill of speaking.

In the next part, chapter 5 you will reflect on what experience you have, where you can get more and how you can articulate that to potential employers, with both written and spoken communication.