I write technical content. My work appears in publications for programmers and on technical corporate blogs. After writing more than twenty pieces, I have developed a useful, if somewhat arbitrary and nebulous, distinction between two types of technical content:
- A Project-Based Tutorial has sample code as its main focus. In a project-based tutorial, you walk the reader through the process of constructing some project using a variety of tools. The reader follows along, copying the code to construct an identical project in their own environment. These tutorials tend to feature multiple technologies (for example, one might require both CSS and JavaScript to build a webpage) and have to maintain a narrow focus on the application at hand to avoid uncontrollable scope creep. Here is an example of a project-based tutorial.
- A Topic-Based Article develops a conceptual understanding. For a topic-based article, you help the reader gain a general grasp of a subject. The reader then takes that understanding and applies it in their specific context. Case studies, news, theoretical discussions, high-level descriptions of algorithmic and architectural topics, and academic journal articles all tend to fall under the category of topic-based articles. Here is an example of a topic-based article.
Making this division is useful because I approach each kind of writing differently, especially at the outline step. Before writing a project-based tutorial, I spend time implementing sample code to present in the tutorial. Before writing a topic-based article, I research the subject area to ensure that I present complete and accurate information in the article. I structure them differently: a tutorial follows the linear steps needed to create the example project; an article allows for a more flexible structure based on what I think best eases the reader into the topic. Before writing, I make sure that my editor and I share an understanding on whether I am creating a tutorial or an article.
The distinction does not mean that topic-based articles cannot have code or project-based tutorials cannot discuss broader themes; it simply refers to the main goal of the piece. Chris on Code, who runs Scotch.io, a website offering programming tutorials that was acquired by Digital Ocean, told me the following about how Scotch.io thinks about different types of content.
- Our main separation is between theory, which is not an article that you can actually create something with, but more of an article that help you understand the concept, and practice. At Scotch we had a category called bar talk, which was simply news. The second category is tutorials, and within tutorials we have theory and practice. Within that, there are other small tags like quick tip, which is an article that you read in about 30 seconds, or real-world project, which is the longer form.
- -- Chris on Code, excerpt from interview in Writing for Software Developers
British writer Anne Isabella Thackeray Ritchie is widely credited with propagating the phrase that became "Give a man a fish, and he will eat for a day. Teach a man to fish, and he will eat for the rest of his life." Her original quote, from the 1885 novel Mrs. Dymond: "...if you give a man a fish he is hungry again in an hour. If you teach him to catch a fish you do him a good turn."
A project-based tutorial can be like giving someone a fish: it is immediately consumable and helps them achieve a specific goal, but it may not help them with future objectives. A topic-based article can be like teaching someone to fish: it will take them longer to solve for their specific case but then they will be able to address similar issues every time one arises.
English humorist Terry Pratchett turned the fishing quote on its head: "Build a man a fire, and he will be warm for a night. Set a man on fire, and he will be warm for the rest of his life." A project-based tutorial can be like building someone a fire; it is immediately helpful and they can use it to light similar fires. A topic-based article can be like setting someone on fire; it is confusing and painful to try to understand a theoretical discussion without context or concrete examples.
You can develop both project-based tutorials and topic-based articles from the same initial idea. There is value in both, and what you create will depend on your interests, your audience, and your publisher if you have one. The important question is, "what do you want to teach?"
- You have to pick your goal per tutorial. For me, picking tutorial goals is interesting because sometimes I want to get a quick tip out so that people can visit the article, find the code snippet that they need, and get out.... There are other types of articles where we do far more long-form tech tutorials. These articles say, "Hey, do you have a couple hours? Let's build something together. Let's make some random, fun project." For me, those articles are very much learning projects.
- -- Chris on Code, excerpt from interview in Writing for Software Developers
Keeping the right archetype in mind while writing can help your piece achieve its goals.
This discussion was cut from my book Writing for Software Developers near the end of its editing. For a step-by-step guide on creating technical tutorials, topic-based articles, and whatever else you want to write for a technical audience, read Writing for Software Developers.
