This is a summary of my writing course as I have taught it in the winter semester 2024/25. Each point here stands for a module with example texts, explanatory material and exercises, and I have also recorded myself presenting all the modules on video. The existing example texts are mostly taken from or written for the field of software development; my plan for the future is to develop sets of example texts that demonstrate the same language patterns for other subjects, e.g. medicine and engineering. The course can be seen as an attempt to translate some of the contents of these books into a form suitable for people working in STEM fields.
If you find this concept interesting, please do get in touch!
Introduction: Technical writing as a medium
We discussed which communication channels work best for you in software development. Everyone agreed that the channel where you get a response is best; which one it is – e-mail or Slack or whatever – depends on the organization. Then we talked about face-to-face conversation and how it involves instant feedback. You can see whether the person you’re speaking to understands what you’re saying, agrees or disagrees, etc. and you can respond to that instantly. If you can, you should always choose modes of communication where you can be in an active dialogue with the other people.
But that isn’t always possible. Sometimes we have to communicate by writing something and we won’t be there when someone receives the text. We can only hope they read it and understand it and do what we want them to do. When we write something like this, we have to think very carefully about our readers – how to make a text that they experience as relevant, useful and easy to understand.
The good thing is that we can work on a text over and over again and improve it so that it comes close to our ideals for overall structure and detail and so that it should be able to speak to the readers effectively.
Part I – Syntax Revisited
- German likes nouns, English prefers verbs.
We looked at a very formal German sentence and discovered that it is a system of nouns connected to each other largely by case markings – word endings and prepositions. Only very simple verbs are used. When we translated this sentence into English, a reasonable result was only achievable by shifting some of the meaning from nouns into verbs.
Then we saw that a text for a similar purpose in English is organized around verb phrases and the verbs are content-rich. That is partly a cultural difference but also reflects the different grammar of English which doesn’t allow us to mark the cases of words so clearly. - English usually sticks to a strict SVO order.
Because of the lack of word endings showing us the case, the syntax of English sentences depends more strongly on the word order and we stick much more strictly to subject-verb-object. - English sentences like a compact SVO main clause.
In English, because the word order is the only way we can identify the subject, verb and object, it’s usually best to keep the main clause (Hauptsatz) short and simple, and put all the other information outside it. This contrasts with German word order, which requires certain information to be inserted into the main clause. - Modifiers 1: How much stuff can we put in front of a noun?
In German we can put complex phrases in front of nouns; English doesn’t accept these and we have to shift the information to a different clause (e.g. one with “that” or “which”) or a different sentence.
In English we freely use words that aren’t really adjectives in an adjective-like function, so we use the term ‘modifier’. - Modifiers 2: Hyphenation
We use hyphens to link the words of a modifier in front of a noun, but then leave a space between the modifier and the noun. Since we sometimes use other nouns as part of a modifier, this makes it easier to see which word is the final noun. If we use the same expression in other situations where there is no risk of this misunderstanding happening, it is written without hyphens. This use of hyphens contrasts with German. - English accepts non-agent subjects
In German, we often hesitate to use inanimate and abstract nouns as the subject and first word of a sentence; instead we use characteristic phrases that move the noun into the sentence. Sometimes the solution to an English sentence is to spot a word in the middle that could actually be the first word and the subject. If you are used to writing in German, you may overlook these possibilities.
Part II – Stories and Information
- What makes a story?
We all relate to stories. Stories have a beginning, a middle and an end. Ends connect back to beginnings. The beginning and end of a longer text are the first and last paragraphs. But each paragraph is also a little story, which also has an end that connects back to its beginning. So a long story (whole text) is a sequence of little stories (paragraphs). - Reader orientation
What do we want our readers to do as a result of reading the text?
What is their level of knowledge?
What are their interests?
Can we see a “user story” for them interacting with our text?
Can we translate (technical) features into benefits?
Do we think one relationship further and understand our “customers’ customers”? - Beginnings: First paragraphs & first sentences
The first sentence must say what is coming. It must set up a problem to solve, or show us the story “in a nutshell”. If the overall text is longer, you can make the first paragraph a teaser for the whole plot. What is “not enough” and “too much” information? That is an art. But most of you, most of the time, don’t get to the point hard enough at the beginning. You know what you have to do! - Logical order of ideas in paragraphs
Use a naturally logical order if the subject matter suggests one, e.g. chronology or a sequence of user actions. We compared ‘real’ texts with versions in which the order of ideas was messed up and noticed that it matters. - Information in sentences
We can divide sentences up into pieces and rearrange them to produce grammatical sentences with the information in a different order. We examined a series of versions of one sentence. We saw that the different versions might suit readers with different levels of knowledge, or that they might put the focus of the story on different items that are in the sentence.
Next, we looked at sentences with “framing” expressions at the beginning, that define a time or place or a relationship to some other part of the story. It’s quite easy to see why these are at the beginning.
After that there are some examples where the beginning isn’t so clearly separated from the rest, but we can still see a pattern: the beginning of the sentence tells us what the sentence will be about (the “topic) and the rest gives us some more specific/new information about it (the “comment”).
And when we look closer, the information often becomes more and more specific, step by step, all the way to the end; in fact, the very last word can be very important for the story. This pattern is called “end focus”.
When we changed this order around randomly inside all the sentences, the result was a paragraph that was hard to read. - A cast of characters
We marked the grammatical subjects in a paragraph and considered whether they function as characters in a drama. Looking at a longer text we could see that the sets of “characters” in each paragraph changed like different combinations of actors appearing in different scenes.
Again, when we changed the sentences in a paragraph around to put other words in the “subject” position, the paragraph didn’t read as well. - Linking expressions
We looked at words and expressions in sentences that link back to previous information, and again contrasted ‘original’ texts with versions in which these features have been removed. Linking expressions may be word like “this” or “that”, “this x” or “that x”, “it”, etc. which refer to something in the previous sentence, or they may also be repetitions or near-repetitions of words from the previous text. - Is repetition bad?
You might have been told in school that “Wortwiederholung” is bad, but actually repetition can be useful. As we just saw, it has a role in linking expressions, and also, in technical writing it is generally good to always use the same name for the same thing.
Sometimes in your texts you will end up repeating ideas because you make multiple attempts to find words for the same concept. When we find these, you will need to decide where this part belongs in the whole text, and: Say it once, say it right.
Interested? Get in touch!