TK: layouts or text?

In the TK note for a web developer, the author writes:

I think that one of the most correct ways to present information is graphical, i.e. Better to see once than hear a hundred times.

Without commenting on the note as a whole, I would like to make a few comments about the different ways of presenting information in the TK and not only in it.

Introduction

Not later than six months ago, we had a dispute with one of the directors, which of the options for presenting information in the TK is preferable - layouts or a description. He stood for mock-ups, motivating this with greater clarity and compactness. I insisted on the description, because, in my opinion, the layout does not provide complete information and can be interpreted in different ways. Then we remained each with his own opinion, but I continued to think about this question, and this is what I came to ...
')

The task determines the choice of tool

Only in this way and nothing else. Agree, it would be utter nonsense to hammer a nail with a screwdriver, only because the screwdriver is easier to hammer and takes up less space. But in order to choose the right tool, you need to know its capabilities.

Layouts

Layouts provide

Visibility
Unambiguous location of elements
Conciseness

Layouts do not provide

Information about the functioning of the elements
Formalization

Text descriptions

Text descriptions provide

Full details of the operation
Full description of the properties of blocks, elements, etc.
Description formality

Text descriptions do not provide

Visibility

Note. By the formalization and the formality of the description, I mean the opportunity to fix something in the contract with the customer and use it as a criterion for assessing the readiness of the work upon acceptance.

Based on these properties, you can create a table of preferred tools for solving various problems:

Task	Preferred presentation
Description of the location of elements on the page	Layout
Description of the purpose and functionality of the element	Text
Description of the properties of the object	Text
...	...

Important note. The above advantages / disadvantages, as well as the table, are nothing more than an example. Naturally, these lists can be expanded, and the set of tasks very much depends on the specifics of the work.

To each his own

The recipient of the information is also important. If this is a designer, then the presentation of information is more important to him (although basic information about functioning is also needed!), And the layout will probably be the best option for him. The programmer doesn’t care much about the layout of the elements; the functionality and requirements are more important to him. The task for him is better to write in words. Customers are different, so here too, everything can be individually.

Examples of misuse

Description of the location using text

An example is given in the note “TK for a web developer”:

Above should be placed logo, the right form for user authorization, just below the logo - the site links, under the links - the top commented news, and even lower block of advertising. In the center should be a search form, under it - the last added ads, then a block of advertising, and the latest news. Under the authorization form should be located block with the latest comments on the forum, and below the block of advertising. At the bottom of the page will be puzomerki counters, as well as copyrights

I agree with the author - the layout is clearly more appropriate here.

Description of properties using the layout

An example with which I have come across more than once is the description of the properties of a product with a “product card” layout (viewing information about a product in the catalog).

Why should there be a text description?

Not all properties of the product can be displayed in the "card"
It is not always possible to unambiguously understand the type of properties from the layout. Example - the price may be a number, or it may be a string, the text may be short or very long, there may be a limited number of pictures, but maybe not.
On the layout, properties of other objects (eg categories) or calculated properties can be taken as goods properties

findings

Are common

"The most correct" ways of presenting information does not exist!
A suitable filing method is determined by:
- Nature of information
- Task (addressee)
The same information can be submitted in the same document in different ways for different users of the document.

With respect to TK (my personal opinion)

The TK is a technical (and often legal, for example, annex to the contract) document and most of it must be presented in text form.
Layouts should be an appendix to the TK, designed to increase the availability of textual information, but not replace it.
In addition to "clean" text and layouts, there are also tables and lists that can increase the visibility, conciseness and availability of information. Sometimes they can successfully replace layouts. Use them more often!