Online documentation authoring is tough. And, it’s not getting any easier without the right tools at hand.
Documentation is not a single article covering some topic, but a set of articles united in a single system with the use of structure, content presentation, common look, references, and other means.
Do technical writers need some special tools to produce such a complex product? Sure! Some tools they can buy, and some they already have. Using them right is what matters. Let’s see what those tools are.
These are the tools for techcomm pros we will talk about today:
Tool #1 - A Keyboard
A keyboard for a tech writer is an equivalent of a sword for a knight. Let’s be honest, you are spending more time with your keyboard than with your friends or family.
If a keyboard plays such an important role in your life, then you should pick a good one. In case you are doubting the idea that a keyboard is able to improve your work, let us assure you - it can.
We bet you know the feeling when you type a lot and you get sore fingers - well, this is it! How isn’t this direct influence?
The industry has made a huge step forward as far as keyboards are concerned. Now, they can combine comfort, style, and personality. We’ve mentioned the word ‘personality’ for a reason - check out this blog post on modern keyboards to find see for yourself what ‘personality’ means in this context. Warning: there turned out to be a lot of crazy keyboards out there.
With the right keyboard your work will bring you more satisfaction. You can type more without feeling tired and simply feel morally satisfied by just clicking those clickety buttons like the ones they have on keyboards with the tactile mechanical Blue Cherry MX switches.
Who doesn’t appreciate a high quality device anyway?
When this rather practical and material thing has been settled, let’s move to the other tools. Less material, but more complex and, perhaps, important.
Tool #2 - Planning
Whatever help system you are creating, it is always a good idea to start with planning. This will help you define the structure in a logical way, without mixing this phase with the actual content creation. Trying to define the structure on the go, along with writing, will likely result in poor structure that will need to be redone later.
Planning is good on all content levels. So, consider following these rules:
-
Plan the entire help system to create a meaningful & logical table of contents.
-
Plan documentation sections to make sure the topics order makes sense to readers.
-
Plan separate help topics to follow your chosen content delivery scheme: inverted pyramid, bottom-top, etc.
-
Every content level may require a different approach to content planning, you don’t have to use the same technique everywhere.
If you take planning seriously it will pay off soon. Consider creating a documentation plan. All the vital information will be conveniently stored in one place, your team cooperation will be established, the scope of work defined, etc.
You won’t have to re-do your documentation plan each iteration - just modify it later, it is totally reusable. So, basically, you need to invest your time and resources once to create a good documentation plan, and then just reap the benefits.
Tools #3 - Targeting
The idea is simple - you need to know your target audience to produce good content. And, the execution is more complex. To "know your audience", you need to define what describes your audience. Depending on the knowledge field and other factors, approaches may differ, and there is no magic bullet.
Let’s give an example from the software documentation field. When creating software manuals, this is what you typically need to know about your readers:
The experience level in the knowledge field. It determines the language of the documentation, the depth of specific terms explanation, etc.
The overall experience with computer software. This determines the technical parts detalization.
Software functions the reader will use often, and those of great importance. This determines the table of contents structure, the quick links you may want to put on the Start Page, and the overall information flow.
Based on the information about the reader, you can choose the right words and the level of details when giving instructions or describing a concept.
It could be much simpler if you were writing for a well-defined and coherent audience. In reality, the audience is often mixed, and it is hard to find a universal language for everyone. In every situation, a solution may be different. Technical writers use various tricks to resolve this complexity. One of the most common approaches is "splitting the audience".
Organize the audience into smaller coherent groups, and try to deliver the content in different ways for each of the groups. For example, you can divide your audience based on the product functions they use, and organize the content as several smaller help systems for each of the groups: Administrator Guide, Programmer Guide, User Guide - each document may use its own "language".
It may appear to be an overkill to create multiple documentation systems. In this situation, you may want to act differently - have only one documentation system, but organize it in a way when each of the smaller groups need to read only a part relevant to that group, as opposed to reading everything. For example, you can extract deeply technical topics into a separate section, or have the Advanced section in some of the help topics.
There are certain techniques that can be of great help - the single-sourcing techniques. They offer certain ways of using a single source for varied outputs. The options include: variables, content snippets, output tags.
Targeting the right audience may significantly improve the perceived content quality. Examples above only illustrate the idea, technical writers need quite a bit of creativity to find the best solution for their specific case.
Tool #4 - Structuring
It is not only the content that determines the readability of a document. It is also important to use the right visual structure. If you just put several kilobytes of text on a page, it may be hard for a reader to quickly jump to the needed part, or to understand what the text is about.
There are many practical approaches to structuring a document: using text blocks to highlight important notes, using columns, creating mini-TOC in the beginning of a topic, using expandable blocks, using text formatting like bold and underlined text, and much more.
To make sure you are always using the right structure, it is a good idea to use several document templates. Each of the templates may represent certain visual structure and may be used for a certain topic type - function reference, concept description, tutorial step, FAQ page, etc.
Tool #5 - Proofreading
Human beings make mistakes. Technical writers are human beings, as we know. At least, most of us :)
That is why proofreading is a necessary step in technical content creation. Of course, many technical writers don’t have a separate person to do proofreading and editing. But this does not mean that this step should be missed for that reason.
You can achieve pretty good results with alternative approaches, even without a dedicated editor in your Technical Documentation Team. Here are some examples of what can be done:
-
Read your own text on the next day/week - this gives you a fresh look at the same text.
-
Read your text out loud - helps you control the rhythm, and catch silly mistakes.
-
Ask your colleagues to read your text - this gives your team an editor-like function, without a dedicated editor position.
-
Automatic spell checkers (online & offline) - yes they are not ideal, but they may be useful.
-
Using text-to-speech systems to listen to your own text being read by a program.
Many technical writers have their favorite techniques. If you have your own "tricks" to implement proofreading, feel free to share with us in comments below.
Tool #6 - Consistency
Online Documentation topics must look consistent across the documentation. To achieve this, follow some rules all the time. For example:
-
Follow strict naming standards for software functionality, UI elements, actions.
-
Stick to one and the same sequence of logical parts of a help topic (may be different for different topic types).
-
Standardize the UI of the documents, and strictly follow this standard.
Even if you are the only technical writer in your company, you can’t keep everything in your head, so you need a written version of your writing rules.
Typically, technical writers use some of the well-known style guides. But they also create their own local style guides that cover very specific things that are not covered elsewhere. It is a good idea to combine both approaches: public styles guides of your choice, and your own extension to ensure a high level of consistency in your online documentation.
We believe you have your own favorite style guides to use in your daily work. Feel free to share your list in comments to spread the knowledge.
Also, we would like add a few words about design. Design is part of the consistency you're striving for, no doubt about that. As user manuals are not just plain text, they are to have some design that would coincide with the corporate style, be subtle but, at the same time, it must be a circuit in the UX mechanism. Details matter here - warning boxes should warn, fonts should be readable and suited for the occasion, coloring should present for sure as we all want our user guides to look professional and create positive image for our company. Also, think about how design for different types of user manuals differ. You can use this blog post on creating documentation templates as a reference or inspiration.
Tool #7 - Documentation Writing Software
This is the only tool you may not have at hand right away. Or you may not have the right one yet.
Based on your needs, your choice of the software may differ. At that, the one size fits all approach does not work long enough. Specific technical writing software is the best tool for specific tasks. So, as a technical communication professional, you may need to have several tools in your arsenal.
Since we are talking about online documentation authoring, as a part of the technical communication field, we can’t avoid mentioning our help authoring tool - ClickHelp. It is built specifically for online documentation, FAQs, and tutorials authoring. The word online here means exactly what it means in the Internet era - the content you create goes online with a few clicks.
With the social and SEO ideas built into the product and extended teamwork functionality, ClickHelp becomes a good choice for creating a modern Online Documentation Portals and documentation sites.
Summary
As you can see, the most important tools are accessible to your right now, and most of them are free! Additional tools may be needed, but the seven tools mentioned above are the basis for good online documentation development. So, go ahead and use them all to produce perfect online documentation for the benefit of your readers.
Happy Technical Writing!
ClickHelp Team