Google, the leading tech company in the world, is renowned for its innovative and exceptional approach to technology. Apart from providing cutting-edge products and services, Google also focuses on improving technical writing skills through various courses and resources. These courses cover various topics, including the fundamentals of technical writing, style and grammar, audience analysis, and documentation architecture.
In this article (and subsequent articles.), I will share lessons I learned from Google's technical writing courses, along with personal notes and takeaways from other courses and readings as well. We'll explore the best practices, tips, and tricks developed by Google to create effective technical documentation and how they can be implemented in your writing.
Technical writing is a unique form of writing that is often used to communicate complex information to a specific audience. Unlike other forms of writing, technical writing requires a deep understanding of the target audience, their needs, and their level of technical expertise.
Understanding your audience is critical to ensuring that your writing is effective, clear, and concise. By tailoring your writing to your audience, you can ensure that the information you are communicating is easily understandable and useful to them.
1. Define your audience
To begin, ask yourself: Who will be reading this blog or documentation? Are they technical experts, beginners, or somewhere in between? What is their background knowledge, and what are their expectations? Understanding your audience will help you tailor your writing style, level of technical detail, and the examples you use to better meet their needs.
2. Determine what your audience needs to learn
Once you have defined your audience, the next step is to determine what they need to learn.
Write down a list of everything your target audience needs to learn to go along with you in the blog/document. For example:
This article assumes the readers have:
Strong knowledge of big O notation.
Proficiency in one programming language.
In some cases, the list should hold tasks that the target audience needs to perform. For example:
Before reading the documentation, the audience will know how to do the following tasks:
Use the Zylmon API to list hotels by price.
Use the Zylmon API to list hotels by location.
Use the Zylmon API to list hotels by user ratings.
3. Fit the writing to your audience
Finally, it's important to fit your blog or documentation to your audience. This means choosing language that is appropriate for their level of technical expertise, using examples that are relevant to their field or industry, and structuring your blog or documentation in a way that makes it easy to find the information they need.
Here are 3 tips that will help you get to your audience:
Use common English
Using complex English words that are not commonly known can make your writing difficult to understand for non-native speakers and even for some native speakers who may not be familiar with those words.
Instead, it's better to use simple and common words that are easy to understand for everyone. If you must use technical terms, it's a good idea to define them or provide a link to a definition to help readers who may not be familiar with those terms. This can help ensure that your blog or documentation is accessible and understandable to a wider audience.
Cultural neutrality and Idioms
Keep your writing culturally neutral. This means avoiding idioms, cultural references, and jargon that may not be familiar to your target audience. While idioms may seem like a natural way to express yourself, they can confuse and alienate readers who do not share the same cultural background or language.
It's also crucial to be mindful of the fact that some readers may use translation software to read your documentation. Translation software often struggles with cultural references and idioms, making it challenging for non-native speakers to understand your writing. Therefore, using plain, simple language that can be easily translated is essential for effective communication.
To ensure your writing is culturally neutral, try to use plain language with simple words and avoid idioms and cultural references. By doing so, you can create documentation that is accessible and understandable to a diverse range of readers.
Avoid the curse of knowledge
Experts often suffer from the curse of knowledge, which means that their expert understanding of a topic ruins their explanations to newcomers. As experts, it is easy to forget that novices don’t know what you already know. Novices might not understand explanations that make passing reference to subtle interactions and deep systems that the expert doesn’t stop to explain.
To avoid the curse of knowledge, you should take a step back and consider what knowledge or context your readers may be lacking. You should avoid assumptions and provide clear explanations and definitions of any technical terms or jargon used in your writing.
Additionally, you should seek feedback from your readers to ensure that your writing is accessible and understandable. This can include usability testing, user surveys, or peer reviews.
In conclusion, understanding your audience is essential for effective technical writing. By defining your audience, determining what they need to learn, and fitting your writing to their needs, you can create blogs/documentation that is clear, concise, and useful.
In our upcoming blog, we'll delve deeper into how to choose the right words and write clear, concise sentences. We'll share tips and tricks to help you streamline your writing and communicate your ideas effectively. So stay tuned!