Technical documentation: where to start?
There is a saying that an ideal product does not need the documentation, as it is clear how to install, configure, and use it. In fact, there is hardly a software solution that comes without reference materials. Developers want their clients to master new tools without assistance and technical support guidance. If you are planning to equip your product with documentation, pay attention to a few key points.
Format
Creating useful documentation implies not only structuring the data, but also presenting this data in the most convenient form. For instance, printed guides are still much-in-demand in the industrial sector. The manufacturers of control cabinets place wiring layouts in special modules on doors. This allows engineers to work with diagrams even if a laptop is not within easy reach.
Online help proves to be one of the most popular formats for software solutions. Such documentation is available on any devices and is indexed by search systems. The indexing turns an information portal into an additional audience capture channel. This way, online help materials become a full-scale marketing tool and contribute to the product’s promotion. About 90% of the global network traffic comes through search engines, and ignoring this fact is nothing but neglecting the audience. The documentation portal’s primary goal is to answer clients’ questions, help to configure a product, and teach how to use it efficiently. The secondary goal is to introduce the product and reach prospective customers.
The product defines the documentation format. Analyze who and under which conditions is going to read it, and choose the format keeping in mind customer convenience.
Tools
In the same way the product defines the documentation format, the format defines the most appropriate tools. It is much like choosing tools for coding: sometimes a simple text editor will do, but in some cases an advanced IDE is a must. A Readme file is enough to tell about a small utility, while complex solutions might require documentation with internal search, templates to keep pages unified, and exporting to multiple formats. In such cases help authoring tools (HAT) are used. These applications help technical writers to work on texts by the means of cooperative editing, advanced exporting features, preparing materials for printing, etc.
Choose the software for documentation in accordance with the product’s peculiarities. Do not overcomplicate.
Team and processes
Some organizations prefer to hire technical writers, others stick to outsourcing as a viable alternative. Either way, once the team is in the ready-to-go state, it is time to deal with work processes. The quality of your documentation depends dramatically on the project participants’ readiness to share information.
It is crucial to get out a message that documentation exists for a purpose. Clients do need it, they read guides to find answers to product-related questions. And this is exactly the reason why developers should communicate with technical writers when new features are to be implemented. In companies that apply the Agile methodology teams get informed during daily meetings. If your organization does not hold such discussions, you must work out the process of knowledge transfer. There might be lots of options, but the goal remains the same, though — technical writers must be aware of everything that is happening around the product. That is the only way to ensure the documentation reflects the product’s current state and it is actually useful for clients.
Technical writers must be aware of all changes in the product.
Think about users to make the documentation truly useful. What kind of information will they need in the first instance? Which format seems to be the most convenient? Answer these questions and eventually you will see the tools you need. Just remember that the documentation’s goal is to make information available to clients.
