If you want to write to colleagues, how to do something

Recently, I have to work very hard with different texts, both my own and others. Therefore, I would like to share with you some observations on what should be paid attention to when writing texts whose purpose is to explain something consistently to other people, mostly little familiar with the subject of the narrative. Examples of such texts may be various manuals, our precious tickets, in which, of course, we do not forget to describe correctly and concisely the steps to reproduce the problem and even documented test cases.
So, including the regime of Captain Obviousness, I pull the sheets on my shoulders like a cloak, shorts over shorts and, stretching one hand in front of me, I'm flying into a thick mass of harsh people with technical education, in order to teach a little of all their lives.
Lyrical digression: today I had some strange problem with the selection of the KDPV, so let it be such a comic:
If you want to write to colleagues, how to do something
Instead of introducing
Next, your text will be called material, and the person passing through the actions described in it - the reader. Only I warn: it would seem where I am, and where the ability to write good texts So the entire post below can be considered a Friday outline, focused primarily on people involved in the testing processes.
The main points worth paying attention to are
Notation of the problematic
An introduction with an explicit designation of the problems to be solved by this material, with the state designation at the initial stage and the designation of the state at the time the reader completes 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 one. If possible, there should be a reference to the source with a description of the correct behavior. If, as the expected behavior, the sense of the author's own beautiful is indicated, then it should be backed up by a confident argument, or even better - to coordinate his opinion with people responsible for the project requirements.
A clear sequence of the described actions
The reader of your text should know exactly what action should be (or precedes) the current one, so that if there are any inconsistencies between what you describe and what is received in fact, he could localize the problem as soon as possible. Any state received by the reader should be clearly traced in the text. If possible, the action steps should be numbered, so if there are any problems, you will be able to contact with an exact indication of the step in which something went wrong.
The uniqueness of
Any described action should not allow ambiguous interpretation. No description of their feelings and emotions in the text should not be. Using the reader's intuition and telepathy to achieve the result you indicated is unacceptable. No texts from the category "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 relevant for test cases).
Clear terminology and inadmissibility of re-complication
The terminology should correspond to the reader and should not contain slang expressions. By the way, all the described actions must be depersonalized. Also, we should avoid describing the elementary, but still try to simplify the description of unnecessarily complex actions.
The screenshots should not serve as an illustration of the situation "in life it happens", but should indicate something that is problematic enough to describe in words. For example, the location of an element in a complex interface or the state of the interface after any action taken. Frames and arrows to draw attention to specific areas of the image - these are our better friends.
Laconic title
And of course the headline - there should not be anything superfluous, but only the essence of the material. And most likely it's worth it to return after your text is ready and make sure it matches the written one.
Instead of an afterword to this habropost
As an afterword, it should be noted that I do not always follow all the described actions, because it's nice to read a dry text :) But before you play with words, so as not to give boredom to colleagues while reading your text, learn how to write it is correct and understandable, so that the reader, first and foremost, quickly and effectively achieves the goals to which his text leads.
+ 0 -

Add comment