The Three Types of Technical Articles: Why Beginners Should Start Writing

Today, I came across a discussion about beginners writing technical articles.

Even though we simply call them "technical articles," articles written by beginners versus experts, or articles intended for beginners versus experts, differ not only in their level of content but also in their purpose and the value they provide. Therefore, in my view, discussions cannot be productive unless we properly categorize technical articles. However, from what I've seen, the perspective of trying to categorize technical articles isn't very common.

So, in this article, I propose a classification of three types of technical articles and reflect on writing technical articles based on that classification.

Note: This classification and the general content of this article are my personal views and are not claimed to be the only correct answer.

The Three Types of Technical Articles

In my view, technical articles can be metaphorically classified into three types: "Learning Notes," "Textbooks," and "Papers." The main criteria for classification are the purpose of the article and the value it generates.

Type	Purpose/Value of the Article
Learning Notes	Written for the author to review and confirm their understanding or to practice outputting.
Textbooks	The primary value is providing knowledge to the reader.
Papers	Provides not just knowledge, but novelty in ideas or technology.

Actual research papers have the critical feature of "undergoing peer review," but the "Papers" category in these three types ignores that feature. I wanted to think of a better name, but "Papers" was the only thing I could think of as a contrast to "Textbooks" on the axis of novelty.

In this classification, Textbooks and Papers have the primary purpose of providing value to the reader in the form of knowledge or insight, but Learning Notes do not. The person who benefits from writing Learning Notes is the author themselves. Typically, Learning Notes are not something from which the reader receives value; I believe this point is the boundary between Learning Notes and Textbooks.

Note that in this article, primary information such as official documentation is not included in these three types.

Compatibility Between the Three Types and Engineers

If we roughly classify the engineers who receive articles into three categories—beginners, intermediate, and advanced—the compatibility between these engineers and the three types of articles would likely look like the table below. ○ indicates good compatibility (being able to receive value from the article), and × indicates poor compatibility (difficulty in receiving value from the article).

	Learning Notes	Textbooks	Papers
Beginner	×	○	×
Intermediate	×	○	○
Advanced	×	×	○

All Learning Notes are marked as ×, but this is a natural consequence since we defined Learning Notes as not being intended to provide value to the reader in the first place. Seeing × might give the impression that Learning Notes are inherently bad, but please be assured that I am not making such an argument.

However, there may be cases where beginners can refer to each other's Learning Notes, similar to "showing each other's notebooks." In this case, it is a prerequisite to recognize that it is a "Learning Note." If you rely on something written as a Learning Note while assuming it is a Textbook, you will likely run into trouble.

Textbooks are for providing knowledge, so they are effective for beginners and intermediate users. In the case of advanced users, since they already possess the knowledge, the new value obtained from a textbook is not very much. However, it is quite common to see advanced users sharing textbook-type articles on social media. This is an action where the advanced user themselves provides new value by utilizing that article. Since textbooks and papers vary in quality, selecting and introducing high-quality content constitutes providing value to the community.

To get advanced users interested in the content itself, Paper-type articles are necessary. In other words, for advanced users to receive new value from an article, they need "insight" that goes beyond mere "knowledge." Specifically, insight includes new concepts, ways of thinking, original reflections, etc.

I have marked the compatibility between intermediate users and Papers as ○, based on the belief that intermediate users can also derive value from paper-type articles. On the other hand, since such insights are often based on knowledge, I have marked the compatibility with Papers as × for beginners, whose knowledge is likely to be unsteady.

Recommendation for Beginners to Write Technical Articles

The pros and cons of beginners writing technical articles are often the subject of discussion. Additionally, the criticism and feedback from intermediate and advanced users on articles written by beginners are also part of the conversation.

In my view, as a major premise, I believe that writing articles is free, so you should write whatever you like, however you like. However, whether what you write provides value is a separate story. If you want the article you wrote to provide value in some sense, there are things you need to be careful about.

Recommendation: Start with Learning Notes

As you might guess, the recommended type of article for beginners is Learning Notes. Writing Learning Notes means outputting the content you have learned. It doesn't matter if it's just a quick note or if it has a solid chapter structure.

However, as mentioned earlier, Learning Notes do not provide value to the person reading them. In my opinion, if someone who considers themselves a beginner tries to provide knowledge to others through an article, they are, unfortunately, overestimating themselves. If you can write an article that provides knowledge to others (i.e., an article classified as a Textbook or Paper type), you are probably no longer a beginner (at least in that field).

Learning Notes are not worthless just because they don't provide value to the reader. The value of a Learning Note is received by the author themselves. Verbalizing what you have learned should help promote your own understanding. Furthermore, by having intermediate or advanced users read it and point out mistakes, you can improve your understanding.

Learning Notes and Pointing Out Mistakes

Here, the phrase "pointing out mistakes" has come up. As a premise, it is out of the question to perform harassment or personal attacks along with pointing out mistakes just because an article is wrong. This article does not defend such behavior at all. However, I believe that pointing out mistakes itself is a good thing. Pointing out mistakes is indispensable for logical communication, and correcting a wrong description improves the value of the article.

In the case of Learning Notes, for some people, the purpose of publishing the article might include receiving corrections for mistakes. Rather, since the author has chosen to publish in a situation where they have the option of either publishing or not on the internet, it is more natural to assume that they intend to accept feedback, including the pointing out of mistakes.

Speaking of feedback, it should include pointing out good points as well as mistakes, but it cannot be denied that when receiving feedback on Learning Notes, there is a tendency to point out bad points (mistakes) more than good points. However, this is not specific to Learning Notes written by beginners. Even experienced engineers tend to point out only bad points when doing code reviews, and the topic of consciously trying to point out good points in code is occasionally seen.

Things to Keep in Mind When Writing Learning Notes

Receiving feedback on your Learning Notes is meaningful, but depending on how you go about it, you may be able to prevent yourself from feeling unnecessarily uncomfortable.

In my opinion, unfortunate feedback occurs when there is a gap between the writer's intent and the reader's expectations. Specifically, this happens when a reader thinks something the writer wrote as a Learning Note is a Textbook. Since a textbook is meant to provide value to the reader in the form of knowledge, incorrect content in a textbook is harmful to the community. Whether pointing out mistakes to correct something harmful to the community is a good or bad deed, I'd say it's a good one. If the content of a textbook is wrong, it's natural for it to be criticized (though, to reiterate, it's not okay to accompany that with personal attacks or illogical points).

To prevent the unpleasant feeling of having worked hard to summarize your understanding only to have mistakes pointed out bluntly, make it clear to yourself that you are writing a Learning Note, and ensure the reader understands this as well. You don't necessarily have to use the term "Learning Note" by quoting this article. Simply writing something like "I've summarized what I learned" or using words that identify the article as a Learning Note type will help. If you do that, kind people might be a bit gentler when pointing out mistakes. Even kinder people might even include some words of praise. If someone still makes harsh criticisms, it means they are someone who cannot correctly understand the intent of the article. While you can't completely prevent such "accidents" where harsh feedback flies your way, thinking of it as coming from that kind of person might help ease your frustration a little.

Since beginners mainly refer to Textbook-type articles, they tend to inadvertently write articles in a textbook-like format. I take a firm stance against writing articles that look like textbooks without the accompanying knowledge, no matter how much of a beginner the author is. As mentioned before, a textbook with incorrect content is harmful. In particular, it is problematic if another beginner mistakes something unsuitable as a textbook and relies on it.

However, if you are a beginner, it is not a problem if your knowledge is incorrect or lacking. The only problem is writing a (seemingly) Textbook-type article in such a state.

That is exactly why I think it's best for beginners to write in a way that communicates the intent of the article (that it was written as a Learning Note type). If you are willing to accept feedback, that is a form of communication between the writer and the reader through the article. If you expect appropriate feedback from the reader, you have a responsibility as the writer to provide appropriate information. This is something that can be done regardless of technical knowledge, and I believe it is a matter of etiquette (though I don't particularly like that word) when communicating through articles in an open technical community. That's why I recommend it as a mindset for beginners when writing articles.

Making it clear within the article "with what intent this article was written" is crucial for helping the reader correctly understand that intent. In fact, this is a fundamental and important practice for articles at any level, not just for beginners. Methods like "clearly stating the target audience" are also excellent ways to convey the intent. Therefore, it is advantageous to practice "communicating the article's intent to the reader" from the time you are a beginner.

Stepping up to Textbooks

As mentioned a little while ago, being able to write technical articles that fall under the Textbook category means you have moved beyond being a beginner. For that reason, releasing an article as a Textbook-type requires a certain amount of determination. Considering the potential negative impact on beginners, Textbooks should not be incorrect, and it is natural that they are scrutinized more strictly than Learning Notes.

Of course, you are free to write a Textbook on any subject (though it will naturally face criticism if the content is wrong). However, this does not mean that the value of any article will be recognized. The value of a Textbook, as stated at the beginning, is to provide knowledge to the reader. I am the type of person whose motivation for writing stems from being able to provide such value to the community. Additionally, the existence of such articles serves as a guarantee of the writer's knowledge level, providing value in the form of building the writer's reputation. Some writers may have this as their objective.

However, Textbooks vary in quality. While having correct information is part of that quality, in many cases, the content of Textbook-type articles is secondary information (which is why advanced users don't find much value in them). Therefore, things other than the knowledge itself—such as "how well it is summarized," "how effectively it promotes the reader's understanding," and "whether sources are clearly cited"—affect the article's quality. For example, an article that just mirrors the content of official documentation without adding any value isn't necessarily harmful if the content is correct, but since people could just read the documentation, it cannot be said to be providing value to the community. If you want to provide value to the community, think about adding some kind of extra value.

Consequently, if you aspire to write Textbook-type articles, you must first solidify your own knowledge. Specifically, to add value like citing sources or helping readers understand, the writer must possess knowledge beyond what is written in the article. As a rule of thumb, if you can explain the correctness of the content (not by rote memorization or vague recollection but with a solid rationale), then that content can become a valuable Textbook.

By the way, even though I call them Textbooks, they don't necessarily need to be heavy, high-volume articles. I believe that articles such as "memos for myself" or "personal experience stories" also fall into the "Textbook" category in this three-tier classification. If you want to move beyond Learning Notes and start writing Textbook-type articles, starting with these types of articles seems like a good idea.

We often see articles labeled as things like "a memo for myself," and even intermediate or advanced users often cite "leaving a memo for my future self" as their purpose for writing technical articles. Even so, I classify these into the "Textbook" category (though they are close to Learning Notes). This is because such articles are still intended to provide knowledge to the reader (perhaps your future self) and are made public. I am not saying you shouldn't publish memos. The reason for publishing a memo is likely because it might help someone other than yourself. Since that is a good thing that contributes to the community, you should feel free to publish them.

Articles such as memos and experience stories are recommended for those starting with Textbook-type writing because they allow for consistent quality. For instance, a record of how you solved a specific error is a good choice. First, the fact that "you experienced it" is an undeniable fact and satisfies the aforementioned "correctness of the content." Writing "I experienced this" about something you actually went through is indisputably correct. Since guaranteeing the correctness of content is often a hurdle when stepping up from Learning Notes to Textbooks, being able to clear that with your own experience is significant.

The added value these types of articles provide, in addition to the knowledge itself, is that they offer specific solutions to niche situations and save the reader's time (eliminating the need for them to investigate themselves). If the process of investigation is detailed and allows visitors to trace back to primary sources, the value increases further. By the time you graduate from being a beginner, you are likely to have experienced one or two troublesome situations, which makes for a great opportunity to write an article.

Regarding the Paper Type

The third type presented among the three is the Paper type. In most cases, articles of this type are what capture the interest of advanced users. Since this is clearly not intended for beginners, I will only discuss it briefly.

Advanced users don't find value in mere knowledge because they already know it. Instead, they are interested in ideas or ways of thinking they haven't encountered yet. What is necessary for that is novelty or originality. Articles containing novel content are also very beneficial to the community and hold high value.

To generate novelty at the idea level, it is not enough just to rearrange or break down the knowledge you've acquired. Novelty is born when you conduct your own original reflections.

Recall what was written at the beginning of the article:

So, in this article, I propose a classification of three types of technical articles and reflect on writing technical articles based on that classification.

Note: This classification and the general content of this article are my personal views and are not claimed to be the only correct answer.

There are words like "propose," "reflect," and "personal views." These words are assertions that this article is of the Paper type (at least, I wrote it aiming for the Paper type, though this article is a bit different from a technical one). Such elements are essential to being a Paper-type article.

However, simply writing delusional idle talk won't make it a valuable article. An article becomes valuable only when the reader is convinced and gains something from it. To achieve that, you set up necessary assumptions and develop logic by combining them with facts to create persuasiveness. By doing so, you can write I believe you can write Paper-type articles; however, since I only spent two years in graduate school, I am not in a position to give guidance on how to write something I've metaphorically named a "Paper," even if it's just a figure of speech. Let's work hard together.

The Three Types from the Reader's Perspective

Up to this point, we have considered things from the perspective of the writer (especially from a beginner's standpoint), but it is also meaningful for readers to be conscious of these article types. When you look at a technical article, think about which type it belongs to. If an article's type is easy to identify, there's a high probability it's an excellent article.

If you think an article is a Learning Note, you shouldn't read it to gain knowledge (this awareness is particularly important for beginners who often read articles for that purpose). Even if you find a mistake, you should be careful when pointing it out. In the case of Learning Notes, the author is under no obligation to write correct content. The only valid purpose for pointing out a mistake is to support the author's learning.

Conversely, if you think it's a Textbook, by all means, gain knowledge from it. If you find a mistake, you can point it out with the aim of having it corrected.

If you're interested in and can gain something from a Paper-type article, it could be said that you possess a fairly high level as an engineer. However, since such articles are more than just simple knowledge, the author's thoughts and assumptions tend to appear. It won't necessarily always align with your own thinking. Just accept that as the way it is.

Summary

In this article, I have metaphorically classified technical articles into three types—"Learning Notes," "Textbooks," and "Papers"—and reflected on the stances that writers and readers should take, particularly toward both Learning Notes and Textbooks. I believe that in a technical community where people of different standings, such as beginners, intermediate, and advanced users, coexist, it is difficult to have discussions that treat all technical articles as one and the same. While I don't necessarily believe that the types presented in this article are the absolute best, why not try being conscious of categorizing technical articles when you think about them?