How to write articles about programming for beginners

Recently, quite a lot of articles began to appear on Habré on various aspects of programming, which are positioned as articles for "beginners." Meanwhile, just for beginners, these articles are often incomprehensible: sometimes too complex, sometimes not answering those questions that they should, sometimes hard for perception.

Let's try to figure out how the article should be written, if you want it not only to like it, but also to be useful to readers.

Identify your target audience

Start by identifying your target audience. The concept of "beginner" - very blurry. Here are a few completely different categories of people who can be called "beginners":
')

• A person who has never heard of programming at all, and wants to learn how to write code.
• A person who knows some theoretical fundamentals (what the compiler does, how compilation differs from interpretation, how the code writing process takes place), but never wrote the code itself
• A person who was engaged in programming, but wants to switch to a slightly different profile (for example, a person has installed simple websites and knows javascript, but wants to learn how to make desktop applications)
• Finally, a person who is quite familiar with programming, but wants to learn a new language or technology.

I think it is obvious that articles targeted at people with different levels will look completely different. However, most of the articles marked “for beginners” are aimed at people who are familiar with programming superficially.

Identify the initial knowledge necessary to understand your article.

Agree, it’s not so difficult to write at the very beginning something like:

“To understand this article, the reader must have basic knowledge of C:
- be able to compile and run the application
- know the syntax, basic data types and control structures "

It does not take much time, but it helps readers a lot. Believe me, if you start an article like this:

Compile the following code:

int main(int argc, char *argv[]) { cout<<"Hello, world!"; } 

then readers may not understand at all what is required of them. Do not forget, once you also did not know how to use the compiler.

Make your article as good as possible.

Good and competent design is one of the keys to easy understanding of the material.

Try to write all the code in its entirety.

I saw articles and books in which the code was cited in separate pieces. This leads to the fact that the reader is hard to understand the code, not to mention the fact that he can not just copy and run this code. Of course, you can, for example, write different functions in different listings. This is even good, as it facilitates understanding. But you should not break apart a logically homogeneous piece of code.

Do not write like this:

An example of a program that displays "Hello, World":

 //   int main(int argc, char *argv[]) { cout<<"Hello, world!"; 

Some (perhaps very useful)
multiline comment from the author

 // return 0; } 

Write like this:

An example of a program that displays "Hello, World":

 #include <iostream> using namespace std; int main(int argc, char *argv[]) { cout<<"Hello, world!"; return 0; } 

Here you can write a long and detailed commentary, and even write that line again

 cout<<"Hello, world!"; 

to which he belongs.

If you need to break the code into several listings, then it would be nice to bring all the code in one listing at the end of the article, or even give a link where you can download this code.

Always check the code before inserting it into the article.

The reader least wants to sit and try to understand why the example from the article does not work.
For the same reason, if your code somehow depends on the environment or compiler, please indicate this separately.

Always comment on the code

I saw a million times in the book there is a listing of 3 pages without a single comment, and then the text describing what this code does is written in solid text. Such things are very difficult to read. Try writing short comments in the code itself:

 #include <iostream> //   cout using namespace std; //cout     std int main(int argc, char *argv[]) { cout<<"Hello, world!"; //  "hello, world" return 0; } 

Do not forget that if the value of a string is obvious to you, this does not mean that it is obvious to everyone. If you want to comment on the code in detail, it would be nice to insert line numbers. It is not necessary to number all the lines in a row, it is enough to do so

 1 #include <iostream> using namespace std; 4 int main(int argc, char *argv[]) { 6 cout<<"Hello, world!"; return 0; } 

In line 1, we include a header file that contains the classes, functions, and variables necessary for working with streaming I / O in C ++. We include this file in order to use the cout object, which is the standard output stream.

In line 4 , the main function begins - it is from this place that the work of our program will begin.

Finally, in line 6, we output the phrase “Hello, world” to the standard cout output stream. To do this, use a fairly simple syntax using the operator <<. The stream object (in our case, cout) is written to the left of the operator, and the expression to be output to this stream is written to the right.

If you want the reader to copy and run the code, you can specify line numbers in the comments, although this is less obvious:

 #include <iostream> //(1)    cout using namespace std; //(2) cout     std int main(int argc, char *argv[]) { cout<<"Hello, world!"; //(6)   "hello, world" return 0; } 

Put yourself in the reader's place.

Imagine which places in your examples might not be very clear, and explain them in more detail. If you are too lazy to describe some things that are easy to find on the Internet or books, just give a link to a resource where you can read about it.

Try not to complicate the code too much and avoid perfectionism.

Do not forget, you write an article for a beginner. If you can make the code easier, it is better to do it. If you want to show that the code can be improved (even if it becomes more complicated), then write about it after a simple solution. Imagine that you are explaining to a person how the return statement works, and for example, you decided to write a function that compares two numbers and returns the largest (or any, if the numbers are equal). Do not write something like

 template<class T> T compare(T a, T b) { return a>b?a:b; } 

Write a simple and clear piece of code:

 int compare(int a, int b) { if(a>b) { return a; } else { return b; } } 

Let it be improved ten times - it does not matter if your task is to show the essence of the method, and not its concrete implementation.

Try to stick to the same level in the whole article.

If you start writing an article at a basic level and talk in detail about simple things, then do it until the very end of the article. If in the middle of the article you suddenly stop explaining some things, the reader may completely lose the thread of the article and get confused.

Stick to the same style throughout the article.

It doesn't matter whether you are writing in an “academic” style, or in the style of “and now, man, let's compile our creation.” It is important that you be consistent and not switch from the formal narrative to the informal and back ten times per article.

Try to structure your thoughts.

You talk about programming - and this means that your story, most likely, is fairly easy to divide into key parts. Try to always do this, because a structured article is much easier to read and understand. A solid wall of text is extremely difficult to read, even if the text itself talks about fairly simple things.

Try to help the reader

Be polite in the comments. If you are asked to explain something in more detail, or add something to the article, try to do it (of course, if you have the time and effort).

Conclusion

I hope my article will help the authors to make their articles more understandable, and therefore more popular. Please write in the comments if you do not agree with any points, or want to add something of your own.