Get best of the week

How to make your article or documentation understand quickly and accurately

Not only the content, but also the structure of the text should be meaningful.

So, if we are talking about a technical or scientific text, for example, an article or documentation, then the form should help to quickly and easily understand the content. For me, in the case of the article, this means that the structure should be something like this:

  • Headline
  • The essence of the article
    Based on these few sentences, along with the headline, the reader must understand whether he is interested in reading this article further.
  • Summary
    Here, in the most concise form, thesis, but with the necessary accuracy and completeness, the essence of this article should be reflected - from several sentences to several pages. Someone deep in the subject may be enough to understand the whole article. But in any case, it is useful for the reader to present in the most general form what this article is about and what conclusions it will receive at the end.
  • The logic of the article
    If the article is long, contains many sections and complex logic, then this chapter can also be useful. This is essentially an extended table of contents. Here, briefly, on one or two pages, the logic of reasoning is stated, dryly, without details. Again, this will be enough for someone to understand everything. If it is difficult, then the reader can skip this (as a table of contents) and read on.
  • Simplified presentation
    If the article is quite complicated, then it would be convenient for many to first understand conceptually what the author wants to say. Therefore, it’s good to first state everything as if you were telling students, missing complex evidence, and perhaps not in such a formal and strict language. For so many, this level of presentation may be sufficient, and they will stop here.
  • Strict presentation
    Here is a strictly professional presentation.

Of course, the structure does not have to be just that. For example, depending on the complexity and length of the text, some sections may be redundant or, conversely, may be added, but the structure should be appropriate for the purpose. In this case, the stated approach allows the reader to understand the content of a complex article as quickly as possible and with the necessary degree of depth. I used this approach when writing the article Nonlinear Differential Equations, the discreteness of space-time and epsilon product . You will see all the items except the last.

I have to read a lot of technical documentation. In my opinion, the generally accepted organization of the text is inconvenient. I don’t have time (and desire) to enjoy the consistent development of the plot and the beauty of the syllable, it’s not “War and Peace”, I only need information and the faster, the better. Therefore, in the case of a new and complex topic, I have to first scan the text several times in search of meanings, conclusions and logic, and only then can I adequately perceive it. That is, in fact, I follow the approach outlined, but in a very inconvenient and time-consuming manner, and it would be much more convenient for me if the information was immediately organized accordingly.

More articles:


All Articles