How to write articles about programming for beginners

    Recently quite a lot of articles began to appear on Habré about those or other aspects of programming which are positioned as articles for "beginners". Meanwhile, just for beginners, these articles are often incomprehensible: sometimes they are too complicated, sometimes they do not answer those questions that they should, sometimes they are difficult to understand.

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


    Define your target audience


    Start by defining your target audience. The concept of "beginner" is very vague. Here are some 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 of the theoretical foundations (what the compiler does, how compilation differs from interpretation, how the process of writing code does), but he never wrote the code himself
    • A person who was engaged in programming, but wants to switch to a slightly different profile (for example, a person types up 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 for himself.


    I think it’s obvious that articles targeted at people with different levels will look completely different. However, most articles marked "for beginners" are aimed at people who are superficially familiar with programming.

    Identify the basic knowledge needed 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 an initial 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 the 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 the article as good as possible



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

    Try to write the whole code

    I saw articles and books in which the code was given in separate pieces. This leads to the fact that it is difficult for the reader to understand the code, not to mention the fact that he cannot simply 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 do not tear apart a logically homogeneous piece of code.

    Do not write like this:
    An example program that displays "Hello, World":
    //Начнем писать код
    int main(int argc, char *argv[])
    {
         cout<<"Hello, world!";
    


    Some (possibly very useful)
    multi-line comment from the author

    //Продолжение
         return 0;
    }
    



    Write like this:
    An example program that displays "Hello, World":
    #include 
    using namespace std;
    int main(int argc, char *argv[])
    {
        cout<<"Hello, world!";
        return 0;
    }
    


    Here you can write a long and detailed comment, and even write that line again
    cout<<"Hello, world!";
    
    to which he refers.


    If you need to break the code into several listings, then it would be nice at the end of the article once again to list all the code in one listing, or even give a link by which this code can be downloaded.

    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 the compiler, specify this separately.

    Always comment code
    I have seen a million times how a 3-page listing is found in a book without a single comment, and then in full text is a description of what this code does. Such things are very difficult to read. Try writing short comments in the code itself:

    #include  //необходимо для использования 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 in detail on the code, then inserting line numbers is a good idea. No need to number all the lines in a row, just do this:

    1 #include 
       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 a standard output stream.

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

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


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

    #include  //(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 are writing an article for a beginner. If you can make the code simpler, 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 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 doesn’t matter if your task is to show the essence of the method, and not its specific implementation.

    Try to stick to the same level throughout the article.

    If you begin to write an article at a basic level and talk in detail about simple things, then do this until the very end of the article. If in the middle of an article you suddenly stop explaining some things, then 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 if you write in the "academic" style, or in the style of "now, man, we will compile our creation." It is important that you are consistent and do not switch from formal to informal narrative and back ten times per article.

    Try to structure your thoughts

    You talk about programming - which means that your story is most likely fairly easy to split 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 grasp, 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 to add something to the article, try to do it (of course, if you have the time and energy to do this).

    Conclusion


    I hope that my article will help 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.

    Also popular now: