How we write articles on Habr: developer experience EastBanc Technologies

Recently, two articles ago, the hundredth article appeared in our corporate hub. In honor of the round number, we decided to summarize our experience a little. This article will tell you how our developers work on articles, what helps them to write and what to look for in their work on the text.



For a start, it’s enough to answer two simple questions:

• Why do I need this?
• What I tell interesting and useful habraoobschestvu?

Then you can take a plan from this article (or come up with your own) and do it.

')



There are creative stages and technical. This article will talk about the creative. Consider:

• Why write articles,
• Where to get the topic for the article,
• Where to find time to write it,
• The main stages of the text,
• What to do if the article "does not go",
• And where to start, if you never wrote on Habr.

We hope that the text is useful to other authors of Habr, including potential.

Motivation: why should I, a developer, write on Habr

There is no single answer and no silver bullet. Therefore, we give the answers of our employees, where everyone can recognize themselves, and with pleasure we will listen to how you are.

• Socialization
  
  Motivates empathy and a sense of community - I want to share emotions and thoughts about the development process with the community concerned.
• Systematization of their knowledge
  
  I like order in my head, and writing an article or even a final text makes it possible to speed up the finding of gaps in understanding and knowledge about the topic. The article allows you to look at the topic from different angles, to find out all the incomprehensible moments, to realize something.
• Interest to understand new and share
  
  Motivates to write about something new for yourself, about something that is fresh in the world of development. If I were engaged in typical tasks, then I don’t think there would be some kind of exhaust from it. By and large, the output is an instruction with or without jokes, which resembles a detailed answer from the Stack Overflow on the question / topic specified in the article title.
• Save time on learning inside
  
  The article is like a synopsis for your colleagues, who still have to tell it later. And so he wrote - and sent or held a seminar.
• Receive feedback and public comment
  
  Views and pluses in the record book to get quite nice, improves karma. Improved karma also motivates writing further. In the comments you can find useful information from the guys who went the same way and have already filled the cones.
• For the good of all
  
  Inspiring the desire to accelerate the development of humanity - if any activity of the author saves people more time than he spent - on average, humanity is likely to benefit in development, since the saved time will likely be spent on useful activity.

Choosing a topic based on utility for Habr

When choosing topics, we focus on our subjective experience and practical cases that we have passed and tested ourselves. Of course, it is assumed that we have studied the literature in advance and will not repeat what has already been written. And according to the rules of good tone, always refer to useful sources.

Good topics

• There are solutions about which the developers say: “In the official documentation about it was not, on Habré, too. I had to tinker. If the decision itself is worthy, then the article will be good.
• Some topics derive from the global task that is set on the project — for example, to provide High Availability and transparent CI / CD. Each step towards this goal — migration to .Net Core, Docker, and so on — can be described in a separate article. At rallies, the joke “to an article!” colleagues like to hint.
• Some of the topics come when you actively explore a new topic. There is a sign: if a developer spent more than 4 hours on research or reading other articles in Google, it means that at least a compilation of the information found should be done, or maybe something new should be written.
• Some texts are born after reading an interesting book, visiting a good conference or even as internal documentation - I want to share new knowledge.

What is good is that it benefits, saves time in the future for readers and gives practical experience, not philosophical speculations about world peace.

Bad topics

There are a great many, but we mention some of them:

• Repeat all known for the sole purpose of being indexed by keywords,
• Direct or indirect advertising of a company or client (see who I work with)
• An article about nothing or an unstructured stream of thoughts.

In general, everything is bad that does not benefit the reader or does not respect him.

The main stages of the text

For the author, the work on the texts goes through 6 creative stages:

1. Goal setting: formulating a theme, idea, and plan. To grope the topic, we answer the questions "What's new, readers will learn from this article," "For whom we write it," "What exactly do we want to share." It is also important for us that the article introduces something new. To do this, we look at the keywords that have already been written on this topic and whether we are repeating ourselves.
2. Notes, or laboratory journal. In the course of working on the task, the developers take notes: save useful links, write reminders anchors for abnormal situations, so that you can then reverse-engineer-notes into readable text. When it comes to the text, it remains only to re-read the "laboratory journal", to reformulate some records using more or less common vocabulary, and then to collect them in a logical order.
   
   

   One of our authors uses the online markdown editor hackmd.io , where he fixes his steps in developing a theme. This tool allows you to share the text, show progress on the article, and most importantly - pre-impose it. The text as a result turns out in which for the publication on Habré it is enough to add kat and to give couple of small strokes. It is convenient to control the structure and layout of the text.

3. We arrange the text. We write out the main ideas and look at their usefulness and place in the structure of the article. It turns out the table of contents, that is, the clustering of text into semantic blocks, which can be perceived without even reading other sections.
4. We edit and rule so that an outsider “not in the subject” can more or less understand the meaning of what has been said. It is possible every day at least once to re-read what is written and to correct what is not pleasant. Editing goes in several iterations, as well as work on the text. At this stage, we look at the language and errors - the unverified text is read as if written by a student in Losers.
5. We look at the text with other people's eyes : the article is read by another developer or PM, competent in this topic. A fresh look and constructive criticism improves the product.
6. Preparing text for printing. We make the final edits, think over the illustrations, choose the suitable hubs - and in print!

The order of these stages is not strict. It happens that the author first of all draws up a plan, reveals each item and details to the desired level, then rules the text in several iterations. And it happens that at first the developer notes the solution of the working task, and already on this basis the text for Habr is born. At any stage, other colleagues who can help with an idea or advice can join the article.



And now from the plans - to action. That is, to the text.

A lot of tasks: how to find time to work on the text

Work on the texts in the style of “moved all the tasks and left with the head” does not add up due to bus factor . Therefore, the authors are gradually engaged in an article in the background of the rest of the work. Often the text is a summary of the actual work task.



One of our authors compared this work with tests. At first you think that there is no time to write tests. Then you embed this activity in the process - and it turns out that there is time. Texts, like tests, help in understanding what is happening. Even if you allocate an article for an hour a day, it will turn out. Of course, in case it is important for a person.



Another writes strictly in the morning. First thing. Knowing that he has a lot of basic work ahead, he can spend 20 minutes on text from the very beginning of the working day. In such conditions, it turns out to write clearly, briefly and in the case.

I want to write an article on Habr and even came up with a topic. Where to begin?

There is nothing new in this issue. Stephen King, George Orwell, Edgar Allan Poe, the Strugatsky comrades, the duet of Henry Lyon Oldie, Richard Feynman and many other authors in one form or another said:

“If you want to start something (write an article, a book or a letter to a friend), but you still can’t do it - there is no time and the situation is better to do it than ... right now!”

One of us helps to open a text editor and pour there a stream of thoughts on the topic. Most likely, then it turns out that this “all is not right”, but the first step has been taken - the work on the article has begun.



There is another way: to find another employee and tell him about the topic of the article. And start the story with the words: "Well, in short ...". And as soon as the first thoughts poured, with a cry of “Thank you!”, Run away to yourself and immediately write down your story. In simple words, with production mats, which you then replace with something constructive.



And for a snack way from the classic - strictly under your responsibility.

I am writing, writing, stuck. What to do?

There are three scenarios that can be applied to the situation:

• Drink a tea and relax. You certainly do not need to force yourself when the text "does not go" - nothing good can come out of such overcoming. This, incidentally, is not only about writing articles.
  
  
  
  But throw work is not worth it. As soon as you feel that you have more or less relaxed - re-read what has been written, some other thought will probably come to mind. Draw a sketch of the structure of the text. Send the text to a colleague.
  
  
  
  Do something around the text, but don't grind out the words. Then the thoughts themselves will begin to dig and you will only need to grab them by the tail - and put, as it is, on paper / text editor.
• Rake all the material in the release of the article all "as is." At this point, you have to add basic thoughts or logically complete the conclusion that there is. If this looks good, then the rest can be moved to the next article.
• A deep and long stupor can mean that the topic is not close, and you do not need to write about it. Such topics should be cut off at the first stage. Or consult a colleague.

If you have other options, how to get out of the creative stupor - share in the comments.

Finally

Write to. Do not listen to anyone and write. It's good. And you will write well - generally excellent. And then the habrobshchestvo will get wiser, materat and get rich.



Finally, useful links on this topic:

• Mail.ru article , how to create author's content for a company blog
• Useful book "Write, shorten" and a site for express checking of texts for clarity
• An article with signs of a good article

Share your recipes in the comments, waiting!