This is the fourth of several posts about the Technical Writing course provided by Google. They will each be tagged Technical Writing.
This particular post covers the unit:
The course itself goes in to more detail in each topic, these notes aim to be a brief review in order to better fortify the concepts covered.
"Technical Writing One teaches you how to write clearer documentation."
According to the welcome page this course teaches the fundamentals of technical writing.
This post covers the following learning outcomes:
- Develop at least four stratgies to shorten sentences.
In software engineering keeping the number of lines of code to the minimum possible is generally positive because:
- Shorter code is typically easier for others to read.
- Shorter code is typically easier to maintain than longer code.
- Extra lines of code introduce additional points of failure.
Technical writing is similar in the following respects:
- Shorter documentation reads faster than longer documentation.
- Shorter documentation is typically easier to maintain than longer documentation.
- Extra lines of documentation introduce additional points of failure.
ℹ Both of the above lists are taken directly from the google course page ↗.
Reaching the shortest possible documentation may take extra time. It is worthwhile though. Short sentences communicate better than longer ones, and they are usually easier to understand.
Focus Each Sentence on a Single Idea permalink
A single idea, thought or concept is enough for each sentence. Each task in a program should ideally be executed by a single statement. The same formula should be followed in technical writing.
A sentence containing multiple thoughts / ideas:
"The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way."
The same sentence broken into a succession of single idea sentences:
"The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively."
Convert Some Long Sentences to Lists permalink
Often a long sentence can be broken into a list instead. This is especially true in technical writing. For example:
"To alter the usual flow of a loop, you may use either a
break statement (which hops you out of the current loop) or a
continue statement (which skips past the remainder of the current iteration of the current loop)."
If ever a long sentence contains the conjunction or, you should consider refactoring the sentence into a bulleted list. If a longer sentence includes a list of items or tasks, you should consider refactoring the sentence into a bulleted or numbered list. For example:
"To alter the usual flow of a loop, call one of the following statements:
break, which hops you out of the current loop.
continue, which skips past the remainder of the current iteration of the current loop."
Sentences often contain filler. The same meaning can often be conveyed with a few less words.
A good example of this is:
This design document provides a detailed description of Project X.
This sentence can loose four whole words (and alter one slightly) and mean exactly the same thing:
This design document details Project X.
Below are some more examples of concise alternatives to wordy phrases. This is a non-exhaustive list. Find the meaning of the phrase and see if it can be conveyed in one or two words, often it can.
|at this point in time||now|
|determine the location of||find|
|is able to||can|
|in spite of the fact that...||although...|
|enhances the clarification of||clarifies|
Reduce Subordinate Clauses permalink
Sentences regularly contain one or more subordinate clauses. A clause is an independent fragment of a sentence which contains an actor and an action. Every sentence has a main clause, and can then contain zero or more subordinate clauses.
Python is an interpreted programming language, which was invented in 1991.
main clause: "Python is an interpreted programming language"
subordinate clause: "which was invented in 1991"
In some short sentences subordinate clauses can be helpful, but not in all. When writing, or editing, keep the idea that one sentence should contain one idea in mind. Does the subordinate clause extend the single idea, or does it branch off to another idea? Consider dividing the subordinate clause into a separate sentence if it contains a separate idea.
Some words which often introduce subordinate clauses in sentences:
A more complex example (containing multiple clauses):
"Bash is a modern shell scripting language that takes many of its features from KornShell 88, which was developed at Bell Labs."
The first subordinate clause extends the main idea, but the second subordinate clause goes in another direction. Below the sentence is divided in two, with the main clause in bold and the relevant subordinate clause in emphasis.
Bash is a modern shell scripting language that takes many of its features from Kornshell 88. Bash was developed at Bell labs.
That and Which
To avoid confusion around different conventions in the English language (British, American and translations) that should be used for restrictive clauses, and which for non-restrictive clauses. A restrictive clause is an essential subordinate clause - the sentence can't live without it. A non-restrictive clause is the opposite - the sentence will still be fine without the subordinate clause.
The example which Google gives in the lesson is the following:
Python is an interpreted language, which Guido van Rossum invented.
"Python is an interpreted language." - This sentence is fine without the above subordinate clause.
And in contrast:
Fortran is perfect for mathematical calculations that don't involve linear algebra.
"Fortran is perfect for mathematical calculations." - This sentence means something different from the one above.
Another example using one of the previous examples but re-arranged:
Bash is a modern shell scripting language, which was developed at Bell labs. Bash takes many of its features from Kornshell 88.
You can also usually place a comma before the use of which, but not before the use of that.