There is an overriding perception that poor documentation is devastating for company’s reputation. It’s true, but the majority of businesses underestimate the value of technical documentation. Good documentation forms the backbone of a company’s success. Click To Tweet
Suppose you have just launched a start-up or kicked off a new project and are struggling to create good documentation. It seems to be daunting at first, doesn’t it? For sure – but we are here to help. By reading this blog post, you will gain key insights into the as-yet-unknown world of technical documentation. In this article, we are going to focus on the top mistakes that IT companies tend to make when dealing with technical documentation. We will accompany you through the process and provide you with some pro tips on how to create successful documentation in two ticks.
As ridiculous as it may sound, IT companies are often lacking in information about themselves: their processes, products, infrastructure and networks.
It is worth mentioning that a company’s documentation encompasses internal and external documents. Many companies consider any kind of user documentation to be of great importance and are likely to disregard the company’s internal documentation. But the knowledge within your company is just as important, or maybe even more important, than the knowledge you send to end users.
|Internal Documentation||External Documentation|
Why Should You Care about Your Company’s Documentation?
Good technical documentation helps users and teams:
- reduce mental efforts;
- minimise time and workload;
- develop consistency and
- improve the company’s brand exposure.
What is the Danger of Poor Documentation?
Those who don’t care about documentation will experience hard times. Poor documentation means poor reputation. Don’t you think so?
A good reputation means trust, respect and adherence between customers and vendors. If customers aren’t responding to your messages, then you need to consider changing your customer service approach. By neglecting principal requirements, a company can gain a reputation of being an untrustworthy vendor. This type of reputation is so easy to obtain and almost impossible to get rid of, so make sure you save your reputation before it is too late.
It takes 20 years to build a reputation and five minutes to ruin it. If you think about that, you’ll do things differently. Warren Buffett
Four Main Reasons Why Poor Documentation Can Spoil Your Reputation as a Vendor
1) Documentation doesn’t meet high expectations
Nowadays, customers are quite demanding and critical. It is true that they want to be treated with the utmost respect in the customer-vendor relationship. As a result, they expect you to provide them with all the information they need to succeed and will want answers to any questions at lightning speed. Considering this expectation, you should understand that they will not hesitate to show dissatisfaction and might simply go elsewhere when instructions are not clear or are poorly documented. Moreover, customers don’t read these documents with the same excitement as they would read novels, for example. They act according to the user manual rule: “Open, find it, go back to work”. This means that after a quick scan of the document, they expect to find the information they need with minimal effort. Therefore, technical writers need to ensure good searchability and usefulness of the documents they create. Nobody wants to spend their time on something that has even a tiny flaw – they want everything ready and well-functioning.
2) Bad documentation means lack of professionalism
Everyone in the business world expects a professional attitude. Technical instructions with a large amount of steps, precise descriptions and annotated screenshots make people think you have spent time preparing them and, as a result, made an effort. This assumption alone makes your documentation feel trustworthy and of high quality. With this in mind, a target reader may now be motivated to check the document more carefully and will eventually find what they need. If a person doesn’t find your documentation professional, there’s nothing to stop them from thinking the same about your organization and the product itself. If you underestimate the value of the company’s documentation, then you aren’t prioritizing the most important aspect of your business. People don’t take such products seriously and won’t bat an eyelid in their direction. Nobody wants to buy from or work with irresponsible and careless vendors.
3) Documentation reflects the process of making a product
A company’s documentation can say a lot about the enterprise, its culture and its internal processes. Documentation requires effort and organisation, and if your colleagues or users notice that a company has low-quality documentation, they will doubt the quality of the product itself. If they are not capable of such a manageable task, how will they manufacture a decent product?
4) People judge by what they see
In reality, the majority of people tend to form their opinion about the enterprise and its products based on the quality of the company’s documentation. It takes less than a minute for users to make a decision about the documentation and therefore about the product. Many users never actually get as far as the user manual, so the first impression does matter. In order to help them meet their needs, you need to provide properly structured documentation that will help form the best image of your company.
If you are interested in how your company can manage its documentation and make it easily available for all members of staff, we suggest watching the video below. Atlassian Confluence is a powerful document management system which can store your company’s knowledge.
Key Mistakes When Dealing with Internal Documentation
No internal documentation at all
If an IT company doesn’t keep track of its own information, what will happen if a few of its key employees leave the organisation? How many ‘how-tos’ exist in the heads of those people? How much of that knowledge, which is essential to your company’s success, is not documented? How will you train new employees in a timely manner? How can you avoid duplicating processes that already exist?
A company’s documentation is the answer to all the above-mentioned questions. By having documentation in place, IT companies had better ensure that losing someone won’t damage the company or place a huge burden on the rest of the staff. Besides smoothing the process when people leave, internal documentation provides introductory material for new hires and reduces the amount of time that other employees should spend in order to train the newbies. Documenting internal processes helps prevent people from having to reinvent the wheel. Click To Tweet If you have a successful process for doing something, make sure you have documented it. Therefore, your colleagues don’t have to spend time creating something that already exists.
In many companies, there is a tendency not to finish writing the documentation or simply forgetting to update some important issues. Such irresponsibility results in serious trouble and losses for the company. In order to solve the problem, it’s better to hire a team of professional technical writers who would be in charge of the company’s documentation. Companies should document their processes and requirements regularly and not wait until the situation becomes really urgent.
Lack of knowledge
There are some instances when you need to approach the IT consultants or the subject matter experts (SMEs) in order to gather the raw material for certain pieces of documentation. Some technical writers misunderstand the purpose of it and try to step into the developers’ shoes, acting on their behalf. This is a very dangerous mistake to make, which may further lead to a poor documentation and poor reputation. Distorted or inaccurate information is the biggest failure that readers never forgive.
It goes without saying that consistency eliminates a barrier between readers and understanding and facilitates communication. Striving for consistency is not an easy task, but it makes comprehension easier. Let us consider what should be taken into consideration while writing any piece of documentation:
- Writing style
- Page layout
- Graphics style
- Heading and text styles
- Word choice
Key Mistakes When Dealing with External Documentation
The document should be as short as possible and as informative as needed. Conciseness is the first feature of good documentation. Nobody wants to spend time reading long, boring passages. If you want to sound professional, don’t waffle. Company documentation is not read for pleasure, and should therefore be informative, succinct and accurate.
Voluminous documentation is part of the problem, not part of the solution. Tom DeMarco
Lack of visuals
Keep in mind that sometimes short videos, graphics and images work much better than just a set of technical terms. A good piece of advice is not to overload a document with the words. Instead of explaining how a programme works with only written information, use screenshots or a short video and it will be preserved in the user’s memory for longer. High-quality visual content adds the real value to your piece of writing and thereby facilitates the reader’s understanding.
Useless and poor documentation that brings no value is a fool’s errand. Every feature exists in two places: in the software and in the documentation. Documentation can easily get out of sync and become incomplete, outdated or just plain wrong. If you don’t approach the SMEs and ask them for the recent changes in software, then receiving updates can be delayed or lost altogether. As a result, you’ll lose customers. Don’t settle for lagging communication between you and your SMEs. There are plenty of software packages available that can assist in sharing changes and keeping your content updated.
Not knowing your audience
Don’t just create content to get credit for being clever — create content that will be helpful, insightful, or interesting for your target audience. David Ogilvy
Keep in mind that it’s better to go the extra mile in understanding your audience to look professional and add value. However, don’t try to guess or assume information about your readers as you can easily make mistakes. Here are four reasons why it is important to know who you are writing for:
1) You will clarify the primary goal of your work
If you know your customers’ goals, you know your own goals. Every piece of end-user documentation has its purpose. People are not alike: they might be of different ages, occupations and levels of knowledge. The needs and goals differ from one person to another. As a writer, you have to ensure you know who your readers are and whether you answered their questions.
2) You will know how to present and frame the information
Remember, approaches vary from one group of users to another. While beginners find visuals such as screenshots easier to comprehend, advanced users, in turn, will appreciate it if you include more thorough information about a product. Besides, knowing your target audience will dictate the vocabulary of the documentation. Characteristics such as the awareness level of the product and the users’ ages and occupations can differ significantly and the words you need to use have to be relevant to the target audience.
3) It will help you decide on a user guide format
Without knowing your target audience you won’t be able to choose the format of a user document. There are two main types of user guides: a functional guide and a procedural guide. The first one provides a description of each individual button and text field while the second one explains how to perform a particular step-by-step workflow with the help of a product in order to solve a single problem. To be precise, a functional guide explains the “whats” of a software product, while a procedural guide provides you with all the “hows” of different features and procedures. Thus, beginners are mostly interested in functional details whereas experienced users are ready to dive deeper into all the possible procedures that are there.
4)You will build a strong image of a trusted vendor
Even though it is generally believed that nobody ever reads user manuals, sooner or later there will be an emergency when customers will need to refer to this help guide in the hope of finding an answer. If it does not meet their needs, they might form a negative opinion about the usability of your product. The consequences of a poor understanding of your target audience can be a spoilt reputation of your product and your credibility as a vendor.
Negligence to SMEs
Most technical writers face an ongoing struggle to create truly successful and useful company documentation. The difficulty increases when the complexity of the product or service requires working with the SMEs who aren’t writers. One important thing to remember is not to try to turn yourself into an engineer. Taking SMEs completely out of the documentation process is a bad idea. If you don’t have a clear idea of how to use the product or service, neither will your users. To ensure your product or service is documented correctly, make it easier for you and your SMEs to work together. Use tools that enable SMEs to create the first draft without too much effort so they can get the ball rolling in the right direction.
On the other hand, don’t go to the other extreme and make the SMEs write all the documentation. Yes, the developers might know the software in a better way, but the chances that they would document it successfully are pretty small. Only checking for spelling and grammar mistakes is not enough when the information itself is not readable. It’s better to hire technical writers for support rather than to try to turn SMEs into technical writers.
To put it simply, the company’s documentation has a great impact on your success as a vendor, so make an effort to create high-quality content. The main goal of documentation is usefulness. If you are creating something just for the sake of it, don’t waste valuable resources. Take these points into account and don’t turn a win-win situation into a lose-lose.