Documentation evaluation criteria

Hi! My name is Ilya and I am engaged in the systematization of information resources^[1]. Unfortunately, many companies neglect this, relying on the sufficient erudition of their employees. With the same success one could say: “Do well, do not do badly.”

This article was inspired by:

Of course, depending on the industry, documentation can and should be assessed differently. But beauty can and should also be influenced. I note that these thoughts apply to the description of IT products, and not to legal and other artifacts. The only exception will be the visual component – clarity of information is a mustIt’s not even a matter of the reader’s qualifications – there is too much information and it is constantly being updated.

So, good one^[2] documentation performs 2 functions:

• Saves resources for product or service support. The better the corporate knowledge base, the more effectively technical support tasks are solved and new solutions are developed.

• Helps in making a decision about purchasing a product or service. All other things being equal, the clearer the description, the easier it is for the client to make a choice.

Based on this, the main criterion for evaluating an article or document^[3] is speed of information perception. That is, how to quickly find what you need or understand what is important?

From the point of view of visual and semantic perception:

1. Structure — general perception of the document:

• What is the reading area, is this format convenient?

• If the article is large, are there headings and a table of contents?

• Is there a diagram of the described solution, system components?

2. Formatting – how convenient is it to read:

• Is the text divided into paragraphs?

• Are the lists completed?

• Are they formalized? hyperlinks?

• Are they highlighted? ключевые слова?

• Is it allocated? важная информация and where is it located?

• Are the screenshots the same size and do they blend with the text?

3. Literacy — the presentation of the material is assessed both in terms of spelling and punctuation, and in terms of meaning:

• “If…” (excess of words, officialese);

• The presence of pleonasms (duplication of meaning);

• Pronouns like “you”, “to you”, “yourself” with a capital letter;

• Complex sentences with too many commas are best broken into simple ones;

• Is the cause-and-effect relationship clear? Where to set it up, what should appear?

  It is impossible not to give an example:

  — Hello, hello! Not far from here, mixed with the cackle of birds and the unobtrusive whisper of the wind, as if illuminating the green waves of the birch grove with crimson, giving off heat like the summer sun in the midst of a sultry, stuffy July summer, emitting a light haze like the rising fog from the expansive surface of a lake at dawn, scaring away the forest dwellers — hard-working beavers, wise hedgehogs and carefree waxwings — the Prishvin House-Museum is burning down. No, there is no need to send out the firemen now.

4. Relevance information:

• Is the description of this version up to date?

• “You can pay for your subscription using Apple Pay or Google Pay”

5. Completeness — you need to study the subject area and ask yourself the question “is everything described?”

• You can simply check the sequence of steps – does the instruction work?

• Are all the methods listed: there is “create” and “delete”, but you can’t edit?

6. Stylistics — is the text written in one style? Artistic or informational?

• “You can refresh the page by pressing F5.”

• “To refresh the page, you must press F5.”

• “An experienced PC user knows that to refresh a page you need to press F5.” (I don't write like that 🙂

For the knowledge base:

7. Detectability (Discoverability) – the ability to find an article by keyword:

“If you search for something in a huge corporate Confluence with 20 thousand pages and get 300 results for your search query, then most likely you will start to feel sad. Because you understand that the relevance of these pages is unclear, and you need to read at least the first 2 pages of the results, scrolling through each of these documents.”

8. Navigation:

• Is it clear what is located in which section?

• How quickly can the required section be found, in how many clicks?

• Is the detailed description only in one place, or is it described differently in each section?

From a technical point of view:

9. Replicability:

• How labor-intensive is it to export source information into different formats?

• Does an employee need to know Git and Markdown, or WYSIWYG enough?

From a business perspective:

10. Price creation and maintenance of information resources.

This criterion has 2 components:

1. Cost of production and maintenance of up-to-date materials;

2. The cost of reading these materials – is it easier to read or to ask a colleague?

This is not only about payroll. Changes in production processes or corporate culture may be needed:

• Who, how and where are the project materials maintained?

• Are there standards for the design of design artifacts?

• How is experience captured in incident management?

• Are there any knowledge sharing activities?

• What is the company's overall maturity level?

Notes:

• [1]: Information resources should be understood as comments in tasks, training and interview materials, employee work regulations, etc. That is, everything that allows you to understand the company's product and its production processes.

• [2]: Documentation is good when the cost of its production and support is less than the benefit it brings (video: “Documentation is about money”).

• [3]: If informally, then such concepts as “document” And “article” can be considered synonyms. In essence, both are the result of processing information for subsequent publication in one format or another. The difference is that hardly any design standards are applicable to the article. As a rule, it is written in a free style.