How to Write a Technical Tutorial - Announcing a New Book on Writing for Developers

Writing for Software Developers, a new book by Philip Kiely, teaches you everything that you need to know about creating outstanding technical content. It gives step-by-step guidance on the craft and the business of creating technical tutorials and articles. Writing for Software Developers also features interviews with 11 experts from the community, including Chris on Code, who founded Scotch. In this article, Philip gives you an overview of the process of creating a technical article.

Writing technical tutorials is a great way to share your skills, earn some money, and generate interest in your project, company, or just your favorite programming language. You do not need to be a famous programmer or a trained writer to create great technical content. Anyone can succeed at writing an outstanding tutorial if they focus on clear explanations of a well-scoped topic for a narrow, defined audience.

Step 1: Your Great Idea

You have a great idea for a technical tutorial, even if you do not know it yet. If you have a topic or title in mind, fantastic!

If you do not know what you want to write about, read Chapter 1 of Writing for Software Developers, titled "Finding and Validating Ideas," for free here. The chapter walks you through a proven process for generating strong tutorial ideas.

There are two important steps to validate your idea. First, as yourself how much information you can fit in a tutorial. You can get a lot done in two thousand words, a hundred lines of code, and maybe a chart or two. The key issue is appropriately scoping your sample application or topic outline to include only relevant information and assume the right level of background knowledge. Right now, you mostly want to make sure that you are within the right order of magnitude. While some publications offer quick tips, writing about the semantics of a single line of code or short snippet might need expanding. On the opposite end of the spectrum, a topic like "Making a Website in Django" would need to be broken down substantially to extract achievable topics for single articles.

Next, consider your article's audience. What does your ideal reader already know, and why are they coming to your article? These two questions are everything you need to define your audience. Be specific. If you can, model your article's ideal reader off of someone you know from work or school, or at least a role or archetype. Do not be afraid to write for an advanced readership for the right publisher, even if it means your work misses a larger beginner audience. On the flipside, beginner- and intermediate-level articles are often in high demand.

Step 2: Preparing Code Samples

When I write a tutorial, I walk readers through the process of building some project. While classic examples like ToDo management applications are a fine method to demonstrate some code, I often find that my tutorials are more engaging and better received when I extract code samples from my personal projects or develop more unique example systems. However, having a great application does not guarantee a great tutorial unless you properly extract code samples from it.

Code samples are one of the most precise and concise ways to explain technical information. The blessing and the curse of code blocks in articles is that they communicate exactly what the author means to express to the computer, but no more. Thus, sample code is an important component of many technical articles, but it rarely stands alone.

Whenever possible, code should be complete and executable with imports and all other context necessary to allow your reader to copy, paste, and run the code seamlessly. While this context can lengthen code snippets and may eventually feel repetitive, it is the best way to ensure that your reader can access the sample code at any point in the article and use it for their own purposes.

The exception is when you are working with large, multi-file projects in frameworks like Django or developing an app for Android or iOS. In these projects, there are dozens of configuration or other files that are full of automatically generated boilerplate. In these cases, use your best judgement in providing sufficient context that the reader can identify where to use the sample code, but do not copy in needless boilerplate. Projects using large frameworks benefit the most from the simultaneous distribution of a repository containing a full, runnable version of the final product that the tutorial constructs.

For an article, good clean code is concise but easy to understand; you should optimize for readability first. Code golf, or the practice of attempting to solve a solution in the minimum number of characters, has no place in sample code, and neither does pointless verbosity. Your code should follow logical architecture and best practices, but unless you are writing about performance or for an advanced audience, it is better to have code that is fast to read than code that is fast to execute. Finally, lint your sample code before including it in the article lest your readers believe it wrong on the account of IDE warnings.

Step 3: Bridging the Gaps

Imagine that you are building a bridge for your readers to cross. On one shore stand your readers, secure in the land of existing knowledge. Your task is to construct a safe passage over a wide strait of uncertainty to the island of new understanding.

Now, you cannot simply lay planks for miles and hope that they stay rigid. To cross wide spans, you must construct additional pylons to support the overall structure. Sample code, cited facts, diagrams and images, and other discrete certainties are the pylons spanning the strait. The outline determines the order and distance between these structures. Your job in the article itself is to span each gap with explanation and intuition.

Each time you sit down to write, focus your attention on one discrete part of your tutorial. With only your outline, research, and relevant code in front of you, write a section in simple, straightforward words. Try not to get hung up on making the language pretty or elaborate, just get the words on the page. It will be much easier to adjust your work when you have a piece to edit.

You know if you are a marathoner or a sprinter, and you can set your writing schedule accordingly. Planning to write a little bit of the article, or one plank of the bridge, at a time will take some of the worry out of writing. Plan your writing time; these writing blocks do not need to be long, twenty to forty-five minutes, but they should be as sacrosanct as any other appointment on your calendar.

Writing for Software Developers

For more detailed information about technical content creation, read Writing for Software Developers.

Like this article? Follow @chrisoncode on Twitter