Correct tutorial

How should a textbook be written correctly? The answer is standard:
- first, the subject of the studied science;
- then principles and methodology;
- then the main sections;
- then subsections of each section;
- and at the end practical details.

This order is considered classical, and a textbook written in this way is exemplary.

In my article, I intend to prove that a good textbook is written strictly backwards in front of. A good textbooks in the field of IT all the more. No wonder there is “Hello, World!”

Suppose, for clarity, that a certain talented pioneer is tasked to study and describe a tree, for example, an apple tree. Where will the discoverer begin to study the apple tree? From the trunk? With branches? No, of course, he will start learning from apples. Apples are tasty and healthy. In addition, quickly run out.
')
After enjoying the apples, the discoverer moves to the leaves. Then he realizes that the leaves are preceded by buds, and the apples are flowers. At what apples appear at the site of pollinated flowers, and behind the leaves, which receive more light, then the stem grows stronger and turns into a branch.

Feel what I'm getting at? The discoverer himself studies science not in the order in which it then expounds it. But let's continue.

Turning to the branches, the discoverer begins to understand how important they are, that useful substances flow along them in both directions, that an important meaning is hidden in the branch, that the branches have the basis of growth and fruiting of the whole tree. After some time, the discoverer moves to the base - to the trunk. The trunk seems to him interesting and very important. It is in the trunk that the whole power of the tree is hidden.

And now, having studied the apple tree from all sides, the discoverer starts writing a textbook and starts it from the ... stem! Students are perplexed: what interesting things can be in the trunk? Well, log and log. And the discoverer of them: learn-teach, the trunk is the foundation! Believe me, I know, I have eaten so many of these apples in my lifetime! Students can only envy the discoverer.

Then students start learning branches, and science bothers them. By the time of the transition to the buds and leaves - causes negative emotions. Flowers are not encouraging. Long-awaited apples are clearly associated with boredom.

Why did it happen?

Students were immediately deprived of the joy of the discoverers. They were given a dry theory. Students were not interested in the end result; they did not give them the opportunity to independently find generalizations. The discoverer deprived students of the historicism of studying science. Such an order is a bad textbook. He brings up formalism, not a lively interest.

What used to be: theory or practice?

Before practice. Based on practice, a theory arises. The ability to analyze and create theories based on practice is an important quality for a person of intellectual work. And it seems that textbook writers are specifically in a hurry to present the theory ahead of practice. Just in case, so that no one suspects their lack of abilities to generalize.

Perhaps scientists value their own theoretical research so highly that they are in a hurry to start? But it also brings a formal attitude towards science. Students begin to customize the practice to the existing theory.

Examples of good textbooks

Textbooks on specific programming languages ​​traditionally begin with a sentence to display “Hello, World!” And everyone who has had to learn them in this way knows how much easier the understanding of the language is. Immediately you begin to understand the syntax, there is a desire to understand the philosophy. Although on the classical writing of textbooks, the output on the screen would have to be studied almost to the last.

Another example of a good tutorial: a practical guide to the parser . In 5 short lessons you feel that you know the language.

Many English textbooks are good, since Western writers are aiming for a quick bottom line.

Examples of bad textbooks

The worst textbook, and at the same time very common, I would call the instructions for using the elevator. It's amazing how much you need to hate all users of this gadget to write such terrible things.

There are quite a few bad Russian textbooks. I would not like to name specific names - people tried after all. They are bad because they are trying to duplicate the manuals, and do not lead the student.

Take, for example, drupal. There are many sites, but not a good tutorial. Remember the recent discussion “I love drupal” - “I don’t like drupal”? There Alexey wrote - you can’t solve the problem - you suffer, then you decide - you rejoice. And if there was one good textbook, it wouldn't be a problem.

This is a traditional situation in the IT field - we are already used to looking for everything in manuals, mostly in English. And when the Russian writer undertakes to write an IT textbook, he does not know how to build it correctly. On the one hand, there is a tradition to build a textbook according to the classical plan (after all, I want to have everything as adults have). On the other hand, information is drawn from different manuals that are structured by type. On the third hand, it’s a tradition to start with “Hello, World!” As a result, the writer is completely lost and writes as it should. Type - as it turns out, and structured.

How to write a tutorial

1. Start with particulars, with the most interesting ones. For example:
- write a tutorial on how to make a cake - start with the preparation of the glaze;
- write a jQuery tutorial - start with useful and interesting examples.

2. Do not forget about the historicism of science. Remember the stories associated with the study, and funny, and tragic. Let students learn romance, feel the dialectic.

3. Leave generalizations, principles, methodology. Give students the opportunity to try to form them themselves, and at the end let them compare their findings with yours. Do not deprive them of the joy of analytics. For example:
- write a JavaScript tutorial - leave the programming paradigm at the end of the book. Let students first practice.

4. Let's practice as much as possible. This is especially important for the IT sector. People need practical solutions. The theory is also needed, but without practice it is dry.

5. In the textbook there must be a detailed pre-index pointer (thanks for the svart hint).

Are all classic textbooks bad?

Classics and history must be loved and respected. Textbooks written according to the classical plan are an excellent method for the codification of science. With their help, you can quickly study the subject, it is convenient to search for some articles. But to entice a student with science according to the classical scheme is very difficult. It is necessary to distinguish between codifier and textbook.