Tao development of reference documentation for IT-product

Hello!

Do you like to read help? And write? I think 99% of you will answer “NO.”

But you cannot get away from creating help, because help is an indispensable means of communication with the user . And so that the creation of the help is not something difficult, unmanageable and incomprehensible, it is necessary to build a clear and streamlined process.
')
In this article, I would like to share our experience and describe the process of creating reference documentation that we use at Alconost .

Roles

First, let's define the typical roles in the project. Usually involved in the creation of help:

• Developer (programmer or product manager);
• Technical writer;
• Project manager.

Here you can add another editor, translators and designer.

In the ideal case (in large companies it is) all these roles are represented by individual employees, but in the harsh reality all of these caps can be worn by one person at a time.

In order for work on reference documentation (and this is not only creation, but also further support and development) not to slow down the development process, the roles of developer and technical writer should be divided.

Sami vs. outsource

If you have a big company, a lot of products and there is something to download a technical writer for 100%, it will be optimal to find or grow a technical writer. It should be noted that a technical writer is a rather rare profession; These people always have a lot of good work and rarely seek it, i.e. the personnel department will have to strain themselves.

An alternative option is to outsource the creation of reference documentation. In this model, the developer reserves only his own role. A project manager for creating and maintaining reference documentation, technical notes, editors, translators are provided by the contractor. Due to the fact that the contractor does help for many clients, its technical writers are always loaded, there are resources and interest for learning new ones.

Separately worth mentioning and help creating tools. It is not always for the developer to purchase software systems for creating reference documentation. If you have a small utility, and you only need Getting Started, do not bother with the purchase of expensive software.

It is useful to give the development of help for outsourcing for one more reason. External technical writers can find bugs, advise the developer some improvements in the interface or suggest their own ideas for the development of the program. This close (and a technical writer is studying a program deeper than a regular user) “a view from the side” will never be redundant. The development of reference documentation can be considered an additional stage of QA.

Requirements for the result

So, more to the point.

It doesn’t matter if you use your own or an outsourcer’s powers to do a certificate, in the first stage you will need a clear idea of ​​what you actually need. Help is different, I wrote about it in the last article. Types and formats of references (infographics) - choose what you want as the final result.

Process

Help development projects are usually quite time consuming, so you also need a control and management tool: you should always be able to see at what stage everything is stuck, which next step, time frame, cost.

The project manager for creating a help system is the “engine” of the whole process. Its tasks include planning, control of intermediate results, ensuring communication between all project participants.

1. Brief

Even if you are going to write help yourself, it will be good to answer a number of important questions about the product first . And if you order a certificate on the side - it will be strange if you are not asked these questions.

This document (brief) will serve as a kind of TK for a technical writer. In the process of filling, you are precisely determined with the requirements for the format of help, the approximate volume of the text, the target audience, languages, the level of preparedness of the user, etc.

2. Content

Properly written content is half the battle. If the help material is well structured, your users will find the information you need in a couple of clicks. Do not rush to immediately write the text, it is better to work out the hierarchy and nesting levels of topics in detail.

You can use a simple spreadsheet to work with the help structure. In the course of compiling the content, you will be able to decide on the moments to be mentioned, keywords (online help on the site will also be used for SEO), the number and content of screenshots, the approximate amount of text. At this stage, you can estimate the timing and budget of the project.

The content is compiled by a technical writer and approved by the developer. After the content is approved, the technical writer starts writing the topic text.

3. Help design

The general design of the certificate can both scare the user, and vice versa, to show that every detail is important for the developer. If the budget allows, and the soul requires beauty, then hire a designer for this task. You have to decide on the templates and page styles for all help formats, choose the resolution and the theme of the screenshots. Small hint: black text (and for apple lovers - gray and blue ) on a white background always looks neat and professional, so do not rush to cram a bunch of colors, styles and other decorations into the design.

All work on the design lead in parallel and regardless of the writing of the text. So you will save time and get a pilot version of help faster.

4. Monitoring Intermediate Versions

Conditionally divide the certificate into several parts and ask the technical writer to send an intermediate version of the certificate after completing each part. Make all adjustments on the text, content and design at the earliest possible stages of the project - this way the writer will be able to take into account your comments and comments when creating subsequent texts.

If you are writing the text yourself, ask outsiders to evaluate the intermediate results of the work. Practice shows that this is very useful.

5. Final version

When all the topics have already been written, take a short pause to take a break and look at the result with a fresh look. Suddenly you missed something? Or maybe you need to cut something?

Read the whole HELP and make the latest edits.

6. Proofreading

I recommend giving the text of the proofreading to a professional editor. Literate text and the absence of typos and errors increase user confidence in the company and the credibility of the developer.

7. Export documentation

After making all edits to the editor and setting the design, make the final export of the help project in all the necessary formats. And be sure to save the help projects, illustrations and all sources in the file storage, so that when you upgrade, do not tear the hair on the head due to lost sources.

Infrastructure

For storing help projects, illustrations and source data, I recommend using cloud storage with multi-user capabilities and version control (dropbox, box.com), as well as online documents (googe docs, office360).

Box.com is the right place for data storage . Pros:

• synchronization with local files
• notification system
• file comments
• version history
• access rights

For briefs, tables with help structure it is convenient to use Google Docs . Pros:

• online multiplayer editing, access levels
• autosave, change history
• expanding functionality with scripts
• no need to buy office suite
• comment system

The final

After completing the work on the help, place the help on the Internet, print a guide, or integrate context-sensitive help into the program. But this is far from the end. The next stage is the update help or translation. About these tasks I will tell in the following posts.

In the meantime, I am waiting for your comments, suggestions and questions. How do you write reference documentation?

about the author

Alconost is engaged in the localization of applications, games and websites in 60 languages. Language translators, linguistic testing, cloud platform with API, continuous localization, 24/7 project managers, any formats of string resources.

We also make advertising and training videos - for websites selling, image, advertising, training, teasers, expliners, trailers for Google Play and the App Store.

Read more: https://alconost.com