A Subjective Guide To Writing (Technical) Articles

A Subjective Guide To Writing (Technical) Articles

Have you ever thought about writing a technical article to share your knowledge with others and had no clue how to do so? You are in the right place. In this article I will try to guide you through the entire process and highlight the parts you should pay special attention to.

First and foremost, you should always plan your article before you start to write. A good plan will ensure you include everything you want in your work, help you gather your thoughts and put them in the right order, so during the actual writing process your mind can focus on actual content, finding sophisticated words and perfecting grammar.

null

Usually everything starts from just a few words written on the piece of paper…

Coming up with an idea can be hard at first, but sometimes only two words are enough to get the creative juices flowing. Personally, I usually create a sort of a scratch book using GoogleDocs where I gather potential research materials, single thoughts about the given topic and short paragraphs written on the spot. This usually happens during executing daily tasks, sometimes weeks if not months prior to actually writing an article.

Another thing that you can do, but it is also a step you can easily skip, is to create yourself a reminder, on your phone, in your calendar or written on a sticky note to constantly remind you to start or keep writing on given topic. Sometimes it is really hard to push yourself to write first few words.

null

A simple mindmap can help a lot in organizing your article around core concepts

If you struggle with smooth transitions between concepts and organization of their smaller details, a good idea can be to prepare a mind map to see exactly how they all are connected to each other. You can use tools like mindmup to easily create many mind maps if you don’t feel like using pen and paper.

When everything seems to be ready, you would think it is time to (finally) start writing, but not so fast. Before you place your fingers on the keyboard, look critically on everything you gathered in the mind map (and in scratch book) and decide if it is valuable enough to turn it into insightful article. If the answer is yes, great, you are ready to start writing!

The first thing I do when creating an article, I write down the headings in GoogleDocs based on what I managed to come up with in the mind map. Remember that the good ones should attract readers’ attention, as well as express what the given paragraph is about — nobody said it is going to be easy! Also, those are not written in stone — feel free to modify them as the content grows.

And now, when you aced your headings, you can fill the space between them with the actual content. Technical articles are a specific type of writing and they often contain code snippets or animated screenshots. If you can try to insert a few of them, it will attract the attention of your readers even more and will definitely help them implement your tips / see how it all works. Still, do not overdo it — animated memes are fun, but this is an article, not an amusement park. Too much animation everywhere can do a great job of distracting a reader from actual content.

null

Sharing, verifying and discussing your work prior to release may not only limit amount of mistakes, but can also introduce completely new ideas to the article

When you are ready with your article, don’t publish it immediately. There is a high chance that something is wrong with it and should be corrected from the technical point of view. I always ask my developer friends to check my work and apply their comments accordingly. After technical proofreading, I send my article to a more linguistic one always making sure the corrections did not interfere with the meaning.

I use Medium to publish my articles, so the next step for me is to create a draft of my article there. If the formatting is acceptable, I go on the hunt for images that will suit the topic of my article and complement it. Here, the image placed in the header is the most important. Make sure it, even loosely, is linked to the topic, which will make your work more recognizable and easier to remember. Ironically, many times this is the hardest part if you want it to be done right.

When everything is ready to go, now it is time to proofread your fine piece of writing once again. There is always something that slips your attention and leave it to the keen readers to find a minor spelling error. Better be safe than sorry!

Finally, the time is here, you are ready to release your masterpiece into the cyberspace. As I said, I publish my stuff on Medium, but I also submit them for publication on the company’s blog, so ask around if your company would be interested in publishing your article as well.

Ensure that as many people as possible have chance to see your writing

Finally, remember to share the good news about your article with others. I post mine on social media like Twitter, Linkedin, Facebook, Reddit. You would be surprised how much recognition can a simple action like this gain you. You can also kindly ask your colleagues to share it on their platforms and just like that you provided yourself free advertising.

And if you think this is all, you might be wrong. Personally, I like to give my article an after-release read, possibly correcting the very last typos and errors. A fresh look after a day or two can do wonders to your work.

And that is all, I promise, you have got yourself an Article, with a capital “A”. Now the only thing left to do is to wait patiently for the likes and comments to your written piece. As you will probably get some feedback, always make note of any constructive criticism to improve your writing and make your publications better and better. Also, always respond to comments in respectful manner and try to understand your audience — this is who matters the most after all.

What is the most important, remember that nobody gets everything right in the first try. Don’t let criticism discourage you, just keep writing and learn from it. Hoping to read from you soon. Good luck!