Recently, I have to work a lot with various texts, both my own and others'. Therefore, I would like to share with you some observations about what you should pay attention to when writing texts, the purpose of which is to consistently explain something to other people, who are mostly not familiar with the subject matter of the story. Examples of such texts can be various manuals, our precious tickets, in which we of course do not forget to correctly and concisely describe the steps to reproduce the problem and even the documented test cases.

So, including the mode of captain Evidence, I stretch the sheets on my shoulders like a raincoat, underpants over shorts and, stretching out one hand in front of me, flying to a thick mass of harsh people with technical education in order to teach some of them all to life.

Lyrical digression: today I had some strange problem with the selection of the KDPV, so let it be such a comic:

Instead of introducing

Further, your text will be called the material, and the person passing the actions described in it - the reader. I’m just warning you: it would seem where I am, and where is the ability to write good texts ... So the entire post below can be considered a Friday attack, focused primarily on people involved in testing processes.

Highlights to note

Problem designation

An introduction with an explicit designation of the problematic that this material should solve, with a designation of the state at the initial stage and a designation of the state at the moment of the reader completing the actions described in the material. In the case of a ticket, this is a mandatory description of the expected behavior of the software and the actual. If possible, there should be a reference to the source with a description of the correct behavior. If the expected behavior of the author himself is indicated as the expected behavior, then it should be supported by a confident argument, and even better - to first agree his opinion with the people responsible for the requirements for the project.

A clear sequence of actions described.

The reader of your text needs to know exactly what action follows (or precedes) the current one, so that if there are any inconsistencies between what you describe and what you actually receive, he can locate the problem as soon as possible. Any condition received by the reader should be clearly tracked by the text. If possible, the steps of action should be numbered, so if you have any problems you can contact with an exact indication of the step at which something went wrong.

Unambiguity

Any described action should not allow for an ambiguous interpretation. There should be no descriptions of your feelings and emotions in the text. The reader’s use of intuition and telepathy to achieve the result indicated by you is unacceptable. No texts from the category "we take an arbitrary value in the range from N to N + 100" - only the exact values ​​of the input and output values ​​used in the examples (especially important for test cases).

Understandable terminology and inadmissibility of over-complication.

Terminology should be appropriate for the reader and should not contain slang expressions. By the way, all described actions need to be impersonal. You should also avoid describing the elementary, but still try to simplify the description of unnecessarily complex actions.

Screenshots

Screenshots should not serve as an illustration of the situation "it happens in life", but should indicate something that is quite problematic to describe in words. For example, the location of an element in a complex interface or the state of the interface after any actions performed. Frames and arrows to draw attention to specific areas of the image - these are our best friends.

Laconic heading

And of course the title - there should not be anything extra, but only the essence of the material. And most likely it is worth returning to it after your text is ready and make sure that it corresponds to the written one.

Instead of epilog to this habropost

As an epilogue, perhaps, it is worth noting that I myself do not always perform all the actions described, because who likes to read a dry text ... :) But before playing with words, so as not to let colleagues bored while reading your text, learn how to write its correct and understandable, so that the reader first and foremost quickly and efficiently reaches the goal to which your text leads him.