12 Principles for your first Technical Article

The importance of writing technical articles in the tech ecosystem cannot be overemphasized. I remember the first technical piece I ever wrote. It was an explanatory piece on the mathematics behind the Machine Learning model, K-Means Algorithm and in hindsight, I can only imagine how much better the piece would have been had I had some sort of guide to guide me. Now, a year, two technical writing courses and 40 technical articles after my first publication, I have culled a list of principles that I believe every technical writer should take cognizance of when writing for an audience.

I think it is worthy of note that one of the most important virtues of a technical writer is patience. It is a lesson I had to learn the hard way. Most often, the beginner technical writer is often too anxious to publish and hence, skips the more important steps.

Generally, the technical writing process can be summarized as follows;

1. Decide whom you are writing for : Every piece has a target audience and this target audience tend to determine the assumptions to be made (i.e. are your readers intermediates or advanced in the subject?), the directness of your sentences and your tone in the article.

2. Identify the information needs of your user : This is the answer to the question 'what aspect of the topic is there so many questions on with little information available?'. It is important to address a subject people want to know about. A common place to start are questions you wished you had answers to as a beginner.

3. Decide how you are going to address your user - which style to apply : Generally, there are two styles in writing a technical article. Functional Orientation which is most suitable for readers that are just getting started with a tech stack. It mostly gives an overview explanation of a product or technology. Task Orientation which is more suitable for advanced usage of a tech stack. This style mostly guides readers through the steps of a process. Eg. How to use JSON with Google sheets.

4. Decide which deliverables to create : Perhaps deliverables is the wrong word to use but it is important to decide on the content your readers need 'delivered'.

5. Decide which tools to use to create your content : This is often a function of the length of the article. Different text editors are more suited for different lengths of contents. At this point, a rough idea of the content should have been determined. This can then be used in picking the right tool to create the content. Note: Microsoft Word is not a recommended tool for technical writing!!!

6. Decide on the structure of your content : A structured article is a good article. The structure of an artice is improved when the writer writes an outline.

7. Decide which information channel to use : The content if not delivered via the right information channel is no use. As such, the onus is on the writer to use the most suitable information channel.

8. Write the article : And then, the part every technical writer wants to jump to.

9. Use images and video when appropriate : Visuals and graphics is perhaps the most important part of every technical piece. Questions like 'why do we need graphics?' and 'when do we use graphics?' are not uncommon. The rule of thumb for when we use graphics is that graphics are used when it is possible to provide the information in a visual way. and when you need to explain complex set of steps or architecture. It is however important to note that graphics in a technical piece has to work in tandem with the texts. In the same light in which describing processes strictly with texts is frowned against, describing these processes with just images without supplementing with texts is no use. Finally, it is advisable to choose a colour that does not confuse or affect people with colour blindness.

10. Publish the first version : Finally, publish! However, it is important to note that this is only the first version.

11. Collect feedback and improve : Feedback is one of the primary drivers of long-term growth. Essentially, gathering for feedback helps you break out of the isolation of writing. When you ask for feedback, you are no longer working in a void, wondering whether or not you understand the assignment and/or are making yourself understood. By seeking feedback from others, you are taking positive, constructive steps to improve your own writing and develop as a writer.

12. Wash! Rinse! Repeat!