How to write an article
From time to time there’s a situation when you have some innovative idea or recently acquired some skill. It definitely did cost you some time and effort. Why not share it with others? Preparing your thoughts for the public consumption helps you organize your knowledge, review the possible flaws and put your idea up for the peer review.
There are multiple methods of sharing your ideas, with two main types used daily: presentation and article. Each of them has its pros and cons: presentation is more interactive and supports better interaction between speaker and listeners. On the other hand, it’s hard to gather a larger crowd for a meeting and not always everyone pays enough attention to the subject. You may be a person that doesn’t feel comfortable speaking to the big audience. An article is not interactive, but readers may access it at their convenience, re-read it and copy code examples if needed (in case of technical articles).
The goal of this work is to encourage you to share your knowledge with your peers by writing an article. This task may be perceived as a tedious, especially when you stare at the blank window of your text editor. I will provide you with a set of tips and tools that I gathered when I did my own writing, so you can achieve your goal step by step.
Motivation and plan for writing
I will treat this as a “zero” requirement, preceding any other component needed to complete your writing project. If you are not motivated to do the work, you will fail for sure. If you are motivated, but don’t have a plan — you will fail with a probability of 95% (not based on any scientific research ;).
Being motivated means that you really want to do something — in our example, write an article. Sometimes this is internal motivation (i.e. you like to organize and share your knowledge), sometimes external (i.e. you like and expect to be praised for your work, your boss told you so or there is some monetary compensation involved). Any motivation is good, the point is that you need to have it.
Contrary to popular belief spread by the internet self-development coaches, it is not enough to just really, really want to do something and miracles will happen. You need to have a plan and execute it. In case of the task such as writing an article I propose really simple, three step plan:
- Read this article.
- Schedule your work.
- Be accountable to someone.
You are on a road to success, as already you are working through point one. This article will give you the knowledge, what exactly you need to do. Next step is the schedule: you need to have some idea, how much time will it take to perform actions that will lead you to the finish. Estimate it, set some dates (remember about holidays, etc.) and write it down. As you have a plan, you need to make it happen. There are not that many people who have internal strength to keep up with the schedule. A good solution is to have somebody to be accountable for — the person, whom you will promise to deliver the results and who will ask you from time to time “how’s going?”. This person may be your boss, your friend, spouse, your company’s blog editor or colleagues from the team. Having such an accountability partner will increase your possibility of success — otherwise it may take you months or even years to finish.
Having covered the basics, let’s start working on your plan.
Have a good idea
The first and most important thing (when you already have your motivation plan) is to have an idea for the article. I assume, that you may have a concept of what you want to share. If it is concrete — that’s great. If it vague — let’s have a look at what you can do to make it more precise.
The subject of your article should be relevant to the readers. Nobody is going to read your article if it is boring or insignificant. It should appeal to the readers’ need of solving some problem (which is most common in case of technical articles), cater to their need of learning something or just reading an interesting story.
The best way to maintain relevance of the article is to define its goal — a short sentence or two that state the purpose of your text. You may find a goal of this article in the third paragraph. Having such motto not only informs your readers, what to expect, but also serves you as a guideline, when working on your article — every step you take should be aligned with the goal. When in doubt if something should (or shouldn’t) be included — ask yourself a question if it contributes towards the goal.
If you don’t have an idea yet, try to create a goal of your article by picking up one of the examples and replacing the contents in the parentheses:
- “The goal of the article is to explain (name of the technology, process, idea) so the readers are able to (do something useful).”
- “This article will show you how to (do something useful) using (name of the technology).”
- “In this article author describes her (experience with something) so the readers (can gain something from reading it).”
There is one more issue that you need to remember when starting to work on your article: you need to be adequately competent in the area that you want to cover. Such competence comes from experience and deep understanding of your field. There’s nothing more annoying than reading a piece written by a person who doesn’t have a clue about the subject. You don’t have to be an expert, just be honest with your readers. If your article is describing your beginner’s experience with some software — don’t act as you have years of practice using it. Write only about the things you are comfortable with. Good rule of thumb is that you should be able to explain and elaborate on any detail that you mention, when asked about it by some reader.
Gather resources
Now when you know what you will be writing about and you defined a relevant goal of your article — it may seem that you should open a blank document in good old Microsoft Word (or vim;) and start typing. But not so fast!
At this stage of work you should gather all the knowledge that you want to share — and some more. It can (and even — should) be random bunch of items (list in text file, post-it notes, pieces of paper, etc.) resembling the brainstorming session. At the end you will have lots of material to sift through when working on the structure of your article.
The resources may be following:
- your knowledge: what you know, what you have learned, some background information;
- example code, images;
- other articles, books, tutorials, whitepapers on similar topics;
- possible questions from readers (with answers);
- known controversies, arguments against your idea;
- technical details, specifications.
Try to cluster these resources in a logical way, resembling how you would like to structure your article.
Prepare structure
At this point you have some knowledge about what you will be writing, but still you shouldn’t open your text editor yet. Your article needs to have a structure — otherwise you will get lost in the convoluted stream of consciousness and hit a dead end. Believe me, this is a very disappointing experience, both for you and your readers.
So, what you should do so that your article leads the reader by hand through the subject is to have a structure prepared before laying any words. You will be able to examine the article’s flow, see if nothing is missing and if the argumentation is right. It’s easier to manipulate the structure than blocks of already typed text.
There are multiple tools that can be used to prepare the article’s structure. You can just write some points on a piece of paper, or draw a mind map by hand. I personally recommend XMind (http://www.xmind.net/) as free multiplatform (Windows, Linux, Mac) solution to prepare a mind map containing the article’s structure. Its interactive interface allows you to easily manipulate the structure.
What this map should contain? The core elements of the map should be main topics that you want to cover, resembling the article’s structure. So, for example, the map for this article contains the following main sections: Introduction, Motivation, Idea, Resources, Structure, Writing, Proofing, Publication, and Conclusions. Then you can break down the main topic to subdivisions, which capture main thoughts and preserve information that you would like to share.
Remember that at the beginning of the article you should introduce the topic to the readers, while at the end — provide some closure and summary.
A tutorial is one of the special cases of technical articles. The goal of such an article is to familiarize the reader with some tool, application, programming language, framework, etc. In such case, remember to balance between technical details and practice. Begin with a general introduction (i.e. paragraph about what the software does) followed by some very simple example. Then add some more details and follow with a more complex example, that readers can follow step-by-step on their own. This approach lets them have a hands-on experience and learn by doing.
You can see the mind map that I have done when preparing to write this article. Have a look here:
Write!
This is the time when — finally — you can open the text editor and actually write. Start with laying out the headers — main sections, then subsections, etc. based on the structure that you prepared. When it’s done, just fill the gaps with text! It’s that easy. It’s best to leave placeholders for images, links, code, so you don’t lose the flow. You will replace them with the real content later.
Remember to keep up the pace that you set in your schedule. If you fall behind, you will need to catch up in the next days.
It should go without saying that you need to respect the copyrights. If you want to cite some text or image, mark this part as a citation and reference author and publication. Never copy content from other texts!
Proofreading to eliminate errors
As writing is often a long and painful process, you would like to publish it straight away when you’re done. But don’t do that. I guarantee that at this stage your text has lots of mistakes that you won’t spot instantly. Give yourself a rest and re-read the article a day or two after you finished the job. Very often you will find some sections that are not clear enough, should be redacted or even removed. At the very best, you will find a few typos or grammar mistakes.
It is also a good idea to share your article with your peers, who can provide a fresh view and valuable feedback. Be open to criticism and appreciate their help.
One thing that you need to remember: there will be always mistakes and errors, no matter how much time you spent on proofreading. So don’t be a perfectionist.
At last — publish
When your article is ready, it’s time to publish it. You may have already some place in mind, such as some magazine, your blog or company website. If not — try to find somebody interested in having your text. Some professional magazine that will pay you a nice amount for your work, while others will just slap your photo and name at the article’s margin as compensation. You have to decide by yourself if it is worth it (sometimes it is!).
This moment is not the end of your work — it’s just the beginning. Readers will leave comments, send you e-mails, point out mistakes that slipped through the proofreading process and ask questions. That’s where you need to get involved: answer questions, respond politely and patiently, fix mistakes. You don’t want to leave your article unattended.
Conclusions
The conclusion is that writing article is hard, but it’s possible if you have a plan. You can’t just sit and start writing. Two most important things are motivation and structure. If you have them, the rest is much easier.
What you should do now? Go step by step, starting with finding motivation and preparing the schedule. Then execute your plan.
I wish you good luck with your work and guarantee, that writing and publishing articles provides great satisfaction.
