Hello, fellows!
I recently completed Google's technical writing pre-courses and wanted to share some of my thoughts on what I've learnt thus far.
I haven't taken any technical writing courses until now, but I've been learning by doing and by reading other people's articles.
However, this did not stop me from writing technical articles and learning from my errors; in fact, I began writing articles and, over time, began these courses, which only contributed to my knowledge. Approaching it this way, I believe it had a greater impact.
So, here are some key takeaways from these excellent pre-courses:
Transitions
The following are the most essential transitions in technical writing:
- However
- Therefore
- For example
I’ve already used these in some of my articles: 1, 2. Be inspired!
Active voice
A significant number of sentences in technical writing should be written in active voice.
What does it imply? It means that the subject does the action expressed by the verb using the following formula:
Active Voice Sentence = actor + verb + target
Here are some samples of active voice sentences from my articles:
Interpretation, like compilation, transforms your source code into machine-readable instructions.
Source - Java vs JavaScript: What is the Difference?
A great team player prioritizes the team's success before their own.
Imperative verbs are usually active:
Finally, be curious, engaged and willing to go the extra mile!
Source - 3 Characteristics of a Great Team Player
Lists and tables
A good list may turn technical chaos into something more ordered.
These are the most common types in technical writing:
- Bulleted lists (unordered)
- Numbered lists (ordered)
- Embedded lists
Here I used an unordered bulleted list:
When should you use Redux?
- When you need to move state between components
- When your app is complex and requires a large amount of application state in several locations across the app
- When app state is frequently changed
- When you need to see how the state changes over time
Tables, on the other hand, should have a relevant heading. Furthermore, every table cell with more than two sentences should be avoided. Aim for parallelism as well!
When comparing Java to JavaScript, I created this table in which I attempted to adhere to these principles.
Audience
Understanding your audience is important. Here are some of the course's key points:
• Define your audience.
• Determine what your audience needs to learn.
• Fit documentation to your audience.
The following video demonstrates how targeting the incorrect audience can be problematic:
Creating sample code
Programmers prefer good sample code. These samples must be correct and simple to understand.
In this article I intended to explain several principles by providing code samples.
I also included some well-known words like "weekend," "saturday," and "sunday" to demonstrate a concept about how to improve code quality.
Final thoughts
That being said, we have reached the end of this article.
There are a lot more fantastic ideas there, so I definitely recommend taking the technical writing courses from Google.
With perseverance and practice, you will quickly enhance your technical writing skills. Cheers until the next time! 😊