I’ve been writing online for almost five years, with a professional focus on technical writing for over two years.
If you struggle to create technical content that is easy to digest, this article is for you.
Where do I start?
If you don’t know where to start to create technical content, decide on the purpose of what you’re going to write.
Ask yourself the following questions:
Why do you want to write that piece of content? Do you want to teach something to the user? Do you want to show the user how to solve a particular issue?
What problem(s) are you trying to solve by writing a piece of content?
Once the reader finishes reading the page, what do you want them to know?
What’s the key takeaway (or takeaways) of the page?
Once you have reflected on the above questions, you should have a clear idea on what type of content you want the user to read. The type of content you want to write may follow under one of the following:
User manual
Tutorial
Blog
API documentation
And more.
How to structure technical content
Structuring technical content is essential to help users navigate and understand it effectively.
When you write technical content, you want to pay attention to the following:
Formatting:
Headings and subheadings
Bulleted and numbered lists
Code blocks (if you want to add code)
Tables (beware that tables may not be mobile-friendly)
Images
Consistency
How to format technical content
When to use headings and subheadings
A headings, also known as headline, appears once at the beginning of a page.
In the digital world, the headline of your content is what displays in bold when it shows up on the results page of a search engine.[Titanium Marketing]
Subheadings are always followed by by headings. You use subheadings to break down a page into multiple sections.
How to use bulleted and numbered lists
You use a bulleted lists when the order in which you present information isn’t important. On the other hand, you use a numbered list when you want the user to digest information in a certain order. It’s important to know this distinction, especially if you want to create tutorials.
Here’s an example of presenting information using a bulleted list:
You can use Java to create a web application.
You can use Java to create an Android app.
You can use Java to to create enterprise applications.
In the example above, you can swap the order, and it wouldn’t make a difference to the user’s learning experience. In some cases, you may want to add the information you really want the user to know the most at the top of the list.
Here’s an example of presenting information using a numbered list:
Go to the website, and download the report.
Add the report to folder abc.
Open the report, and write your name, surname, and date of birth.
In the example above, if you swap the order of each item in the list, you’re going to disrupt the user’s experience. For example, if you tell the user to add the report to folder abc, the reader may wonder where they’re going to find the report in the first place.
Your purpose as a technical writer is to offer a seamless user experience by eliminating barriers that may lead the user to drop out of your content.
As someone who reads a lot of online content, I see this mistake too often: taking steps for granted, using bulleted lists instead of numbered lists, and vice versa.
Add code blocks
This is relevant if you want to add code blocks to your content.
Ensure code blocks and terminal commands are wrapped in triple backticks, so readers can easily copy and paste the code in to their editors/IDE.
Add tables
Tables are good at presenting information in a simple and concise manner. They don’t help with you want to present detailed information (in this case, you may want to use a bulleted list instead).
Beware of tables with too many columns and rows, as they’re often mobile-unfriendly.
Add images
Images are an excellent to ehance the content experience. Images can include:
Diagrams
Screenshots
Videos
Charts
And more.
Beware of adding visual content that can quickly go out of date.
How to write consistent content
Consistency in technical writing means that information is presented in a unified fashion. Consistency especially applies to formatting and grammar.
To give you an example: some specific terminologies are written in all capitals (an example of this is VAT).
Writing the same word in different ways throughout the content may imply that the word carries different meanings.
It’s your responsiblity as a technical writer to ensure that content is coherent from start to finish.
As you write content, revisit it to ensure that it stays consistent.
If you want to learn more about writing technical content, read the following resources:
