This article has been published on the 17th of December 2019.
Publishing information on the internet, in the form of a blog or a whitepaper, has become easier and easier over the past years. This allows anybody to be heard, including those who would have been ignored in the past. However, due to the ease of publishing, there are a lot of articles that have no clear structure.
In this article, several common errors regarding the structure of articles are explained, along with tips on how to improve the structure. The observations in this article are mainly based upon the feedback that I have given in the Malware Research Telegram group. Even though the reviewed articles are mainly based on technical articles, any article in any field can benefit from these tips.
This website will be used as an example in all observations to ensure that none of the examples can be taken personally. I’d like to thank Jacob Pimental, Victor ‘p3tr0v’ Neves, Nikhil Hegde, and several others who would like to remain anonymous for their blog submissions upon presenting the idea for this article.
Note that the tips in this article can be applied to more than writing articles, since talks and workshops also require a proper structure for the audience.
The term error can be considered too strong, as it is not always a matter of right and wrong. However, the term will be used in this article to clearly differentiate between clear examples and unclear examples. Below, multiple common errors are given, together with examples.
Stick with the audience
Every article is written for an audience, whereas some articles might target a more specific audience than others. Examples that are given within the article should match with the audience. If the target audience is non-technical, including code examples will not provide clarity to the reader. Avoiding specific examples in an article that targets a technical audience, will result in a vague article.
Additionally, one has to provide background information when presenting research. Explaining too little will make the article hard to understand for the targeted audience. Explaining too much will bore readers, as the majority of the article will then be seen as common knowledge to the reader.
For example, the audience of this website is technical, whereas the audience of a specific post varies slightly. News sites tend to give a more generic overview of topics, to make them understandable for a more generic reader. Providing specific changes in economic models is not the area of expertise most reverse engineers are experienced in. As such, a more generic explanation of such changes would make sense.
Stick with the chosen tone
Every article has a tone, either more formal or more informal. The tone of an article is a constant, meaning it should not change. If the tone does change, it will confuse the reader. As a result, the reader might think that the article is pieced together in a haste. The focus of the reader should be on the article’s content, not on its structure.
Additionally, the tone of an article might be appreciated by some people, but not by others. Writing in an informal tone and including memes is likely to be the opposite of the content that is present in this course. One can choose to make the subject more lighthearted by using an informal tone.
Alternatively, one can use a formal tone to focus on the content of the message. The tone of this website is rather formal, as the focus is to share knowledge without distracting the reader. When revisiting an article at a later stage, the formal approach will help to the reader to quickly find the information (s)he is looking for.
Introduce the subject
The introduction is important, as it provides a lay-out (or roadmap) of the content in the article. The reader then knows what can be expected from the article, in what way the information is presented, and for who it is meant. Deviating from the given lay-out in the introduction makes the article unclear. When the message of the article is unclear, readers might stop reading or have trouble finding out what the author’s message is.
In any article within this course, an extensive introduction is given that explains the article’s goal, as well as the more specific areas that will be covered. By only reading the introduction, it is clear for the reader if the article is of any use. Without an introduction, one needs to guess what topics are covered.
The use of pictures, or lack thereof
Pictures can greatly improve the clarity of an article, by being either present or absent. Using too many pictures, or too few, will make the article hard to understand. Including too many details in a single picture will decrease the clarity at best, and cause confusion at worst.
When using one or more images, one has to think carefully as to why the image(s) are of use. In some cases, an image might be used as a header at the top of an article. In this case, the image should be appealing to the eye and somehow relevant to the topic that is covered. Images are also used to provide insight into the process that is described within the article. Often, assembly language excerpts are provided in a screenshot to illustrate a specific function.
In this course, there are no images present. This is done on purpose, as one is only capable of properly explaining something when (s)he fully understands it. Images would provide an easy way out, and leave the reader with questions. To avoid this, no images are included and all code excerpts are added as text. This provides the additional benefit that readers can follow along more easier, which is also a highly prioritised goal of this course.
Note that the complete explanation without images can only benefit the reader if the explanation itself is clear and precise. Failing to provide such an explanation will cause the reader to be left with even more questions.
Align the structure with your goal
An article can have one or more goals, such as conveying a message, explaining a concept, providing guidance, or showcasing a project. When showcasing a project, the end result is shown to the user. Showing how to install the tool step-by-step without making this clear from the start, will turn readers away. If the article is presented as an installation guide, the structure and goal align, thus matching the expectation of the reader.
A proper introduction will help to align the structure with the goal, but does not solve the issue in all cases. If the article’s goal is to showcase a project whilst also going into great detail regarding the project’s set-up, it is possible to write an introduction that provides the reader with this information.
Within this course, each chapter has a short introduction that highlights what is taught in the complete chapter. This way, the expectations of the reader are already set when picking a single article from a chapter. The article’s introduction will fully clarify the content to the reader, who then decides if the article is worth his/her time. This way, the reader is well informed before making a decision.
Pick a single language
Most people do not speak more than one language. Posting articles in different languages will confuse most readers. Since information is often widely and quickly available, one can pick another source to get information from. Note that articles of exceedingly high quality will always stand out. Their availability is also limited compared to other articles.
If half of this course was written in Dutch, it would have been frustrating for most readers to follow along. Using an online translation service does not provide the best results, as some things are lost in (automatic) translation. When everything is in the same language, readers know what to expect and what to prepare for.
The structure of an article is up to the author, with a few exceptions such as academic reports. Not all examples might be applicable to any given article, but there are at least a few examples that ring true.
Additionally, it does not have to be a lot of work to incorporate these tips into your work. By keeping these tips in mind when writing the lay-out of the article, the first draft is already a rough representation of the final outcome. Changing the structure of an article after it has already been written will amount in much more work, as the article has to be rewritten.
Lastly, it is easier to work with a structure that is coherent, as it makes the story logical for both the reader and the author.