Table of Contents
Writing a technical tutorial is a great way to share your skills and generate interest in your project or company, or promote your favorite programming language. You don’t need to be a famous programmer or a trained writer to create quality technical content.
Experience teaches us that anyone can write a good tutorial if they study and understand a specific topic, explain it in an understandable way and have clearly defined the audience they want to explain it to.
Here are a series of steps that can help you achieve this goal.
Technical tutorial:
Step 1: Profile your idea
There are two important moments to validate your idea. First, ask yourself how much information a tutorial supports.
You can accomplish a lot with 2,000 words, a hundred lines of code and a graphic or two, but the key is to define the sample application or subject matter, focus on it to include only relevant information, and determine for your presentation the appropriate level of background knowledge the reader should have. You gain conciseness and effectiveness in your presentation.
Some publications offer brief suggestions. But writing about the semantics of a particular line or piece of code may require a longer explanation. A topic such as “Creating a website in Django” may require a more substantial deployment of content; you may need to build several articles in the process.
Second, always consider the audience for your article: What does your ideal reader need to read? Why is he or she accessing your article? These are the questions you need to ask to define your audience.
If possible, model the ideal reader after someone you know at work, school, in your neighborhood or circle of friends. Even based on information about trends or the demands of a specific group you have met, for example, in a newspaper article.
Don’t be afraid to write for an advanced audience, even if this means that your work demands a little more from a general or less advanced audience. Basic and intermediate level articles are generally more in demand.
Don’t oversimplify to the point that your presentation is incomplete or has gaps. Try to find an effective balance between the level of content and the clarity with which you develop it.
Step 2: Prepare code samples
A good way to write tutorials is to walk readers through the process of building a project.
While task management applications are good examples for demonstrating code, pulling code samples from personal projects or more unique systems often makes for better received tutorials. However, having a great application is no guarantee for a good tutorial unless you use the right code snippets.
Code samples are the most accurate and concise way to explain technical information. In articles, code blocks communicate exactly what the author intends to convey on the screen, but no more. Therefore, it can be said that code snippets are an important element in technical articles, but they do not stand alone.
Whenever possible, the code should be complete and incorporate all the imports and context necessary for the user to copy and execute the code without any problems.
Although the context may extend the code snippet and, in some cases, seem repetitive, it is the best way to ensure that the reader can access the code snippet at any time and use it in their own endeavors.
The only exception is when you are working with projects using frameworks such as Django or .NET, or if you are developing native Android or iOS apps. In these projects there are dozens of configurations or other files full of repetitive code. In those cases, provide enough context so that the reader can identify where to use the example code, but don’t copy any unnecessary code.
In an article, good code is concise, but easy to understand. You should optimize your code to be readable. The practice of trying to solve a solution using the least number of characters has no place in example code, nor does meaningless verbosity.
Your code should follow a logical architecture and good coding practices. Except if you are writing for an advanced audience, code that is easy to understand is better than code that is fast to execute.
Finally, adjust the structure of your code correctly. This prevents readers from thinking it’s wrong because of warnings in the IDE.
Step 3: Close the gaps
Imagine you are building a bridge for your readers to cross a waterway. Your readers are on the edge of existing knowledge. Your task is to build a safe route, over a strait of uncertainty, to the shore of new knowledge.
You can’t just lay slabs for miles and expect them to stay secure. To cross large gaps, you have to build additional pillars to support the entire structure. Example codes, quotes, diagrams and images. Your conception determines the order and distance between those structures. Your job in building the article is to fill each gap with precise explanation and intuition.
Every time you start writing, concentrate your attention on a small part of the tutorial. With only your ideas, research and the relevant code in front of you, write each section using a simple, straightforward approach.
Avoid focusing too much on finding elaborate or fancy language; just get the words on the page. It will be much easier to improve your work once you have something written that you can then edit.
Plan your writing times appropriately based on your pace. Determining whether to write a small part of the article, or a whole section at a time, will take some of the stress off when you decide to do it. Stick to the schedule as you would any other activity. Periods of no more than 45 minutes may be sufficient.
Final suggestions
The book Writing for Software Developers, by Philip Kiely, provides many elements you need to know to create quality technical content. It provides a step-by-step guide to the art of creating technical articles and tutorials. In addition, you can find interviews with 11 community experts (Scotch.io, Indie Hackers and Stack Overflow, among others).
