Writing a Technical Description: Best Practices
Technical Description — Definition
A technical description may be an individual document or a part of some other document. It can consist of only a couple of sentences or be several pages long.
Technical description is a type of technical documentation that helps readers understand the product or object described, its features, functions, parts, size, shape, design, how it works, and many other characteristics.
As today everything has gone online, including technical documentation, a technical description may contain very nice-looking and helpful visual elements: infographics, pictures, interactive elements, and even videos. Some of them may contain sound recordings to demonstrate particular sounds that simply cannot be described other way. All that makes information very efficient and straightforward.
Why Write a Technical Description?
A technical description is a document that gives the audience a clear understanding of a product, service, or mechanism. Based on that knowledge, customers see what they deal with and get an idea of how to use it.
No matter who your target audience is — experts or non-experts; they all are looking for relevant and clear information. If your technical description meets their needs, you’ve done a great job!
Writing a Technical Description — Tips
Each technical writer wonders how to create an efficient but enjoyable technical description. That’s always challenging, and there is no universal instruction. But here is a list of things you should keep in mind to produce nice technical descriptions:
Keep Purpose in Mind
Always keep in mind the purpose of your technical description. It affects the way you write: the terms you choose, the length of your sentences, how you divide information into blocks, logical connections between sections, and many other things. You may even specify the purpose right at the beginning of your technical description to let customers clearly see what information they will find.
Demonstrate Your Expertise
If you want your audience to treat you like a real expert, it is definitely the worst option to use excessive terminology. Everyone can boast about using complicated words. But does that help customers understand the core of information? — Not really. Show your audience that you perfectly know your product, its modifications and versions, how it works, all its peculiarities — that’s the best way to gain authority. Use plain language to describe all that. Your audience will like it as no one wants to strive to understand what was meant. Customers appreciate when complicated information has already been processed and analyzed, and they see the final result — simple and comprehensive output with no excessive terms. On top of that, if you want to improve the searchability of online technical documentation, it is better to refrain from using too complicated language. It should be as close as possible to search queries.
Use a Plan
Technical descriptions can be diverse: they describe different objects, serve different purposes, are created for different industries with different standards. But there is a general plan that you should keep in mind to create a comprehensive technical description:
- What is the object?
- What are its functions?
- What does the object look like?
- What does the object consist of?
- A brief conclusion or summary.
You can easily modify the above-mentioned plan according to your needs and purposes.
Think About Design
The well-thought-out design doesn’t only beautify technical descriptions but also contributes to the message of the document and its readability. Some parts of content can be hidden to let your online document “breathe.” For example, your document may contain some very technical details like stats, specs, etc. You can use pull-out elements to show them. Some readers will be interested in these details, while others will not.
Here is what these elements look like:
If you don’t know how to do that, here is a piece of code:
<details style=”padding: 6px 12px; border: 2px solid #00b353; border-radius: 4px;”>
<summary>Examples</summary>
Your text
</details>
In case you don’t want to place Examples (or any other text) in a box, you can use this piece of code:
<details>
<summary>Examples</summary>
Your text
</details>
Here is what it will look like:
Another way to structure information visually is to use a list. It makes the information easily scannable and gives a clear visual division into the body of the text and more detailed information. Here is what a list looks like:
And that’s how you can create it:
<ul>
<li>Screencasting tools</li>
<li>Video tools</li>
<li>Diagramming tools</li>
<li>Wireframing tools</li>
<li>etc.</li>
</ul>
One more method can help you write short and informative documents, which is a great solution when creating technical descriptions — using note boxes. Read about how to create them in this post — Create Note Boxes in Online Documentation with HTML and CSS.
And, if you want to insert a video, that’s how you can do it:
<video width=”700px” controls=””>
<source src=”/resources/Storage/video/sample-video.mp4" type=”video/mp4">
</video>
In case you want to track statistics and you have a YouTube Channel, you can do the following: upload your video to YouTube and simply generate the embed code to insert it in your technical description. You’ll kill two birds with one stone: you’ll be able to track your video’s stats, and the video will be available even for those users who don’t read your technical documentation.
Best Tools to Write a Technical Description
Choosing a tool for writing technical descriptions is not an easy task as the choice is wide. Consider your needs to make the right choice. Here is the list of questions that can guide you:
- Cloud or desktop? Today, the majority of tech writers choose cloud tech writing tools. They allow working from any place and any computer and establishing the work of remote teams.
- Should documentation be updated? As products change rapidly, technical documentation changes as well. Choose a tool that will allow you to quickly update your technical documentation. Make sure you have access to the version history of your docs. In case you make a mistake, you can roll it back.
- Where to host online documentation? Choose a technical writing tool that will help you solve this problem. It is great if you don’t have to bother about a server and a website for your docs and, of course, the loading time of your content.
- How to migrate technical documentation? If you already use a help authoring tool, but you are not satisfied with it, do not be afraid to change it. Make sure the new one offers an easy mechanism of migration and supports the format of docs that you use.
These and far more problems can be solved by our help authoring platform, ClickHelp. Do not hesitate to book a demo with us to learn more.
Conclusion
Creating enjoyable technical documentation is challenging but manageable. In a perfect world, you should start with choosing a tool that meets all your needs. Then comes writing. Ideally, a tech writer should know the basics of HTML and CSS to create really nice online content. It means that the set of skills for tech writers has broadened. We’ll see what other skills will be a must in a couple of years!
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices
