One of the ways I support my development teams is by curating the internal documentation they create to on-board new members.

Developers don’t always make the best writers (and I say “not always”, because in my career I’ve had the opportunity to work with excellent developers that are also highly skilled in writing and structuring information in a logical way, so as for everything else in life, there are exceptions to the rule).

When it comes to internal documentation, technical writers can never beat the knowledge that a developer has about a feature that he/she has been working on, usually for weeks or even months, and that is meant to be used by other developers. The team knows the ins and outs of the code, they have often struggled to find the root cause for a bug and have drunk tons of coffee while trying to make it work.

Developers, on the other hand, don’t need to know how to write great tutorials, it’s not their job after all, and very often cannot afford to devote much time into this either.

After spending some time reviewing what the teams produced and sending corrections back and forth, which was not only boring, but also time consuming, I started thinking about possible ways to optimize this workflow.

How to get the best of both worlds, speed up the documentation process and ensure the output is structured and consistent? The answer to this is: you can provide your teams with a tutorial template containing the base structure and information about what to write in each section along with some examples. This will ensure that all teams follow the same structure and the content is consistent and contains all the information required.

As a technical writer, I always try to be an asset to my teams, never a liability. This includes using the same languages, tools and applications that my colleagues work with on a daily basis. In this case, this translates into writing the template in a Markup language (for different reasons I chose AsciiDoc over Markdown, I might explain this in a future post), so that the content can live together with the code, and follow the docs-as-code principle.

After concluding that a structured template based on AsciiDoc will lead the team to create better internal documentation, I started to design the template.

Tutorial Template

General Guidelines

I use this section to provide general information, tips and tricks. I keep the information hidden (//) because it is not to be seen by the readers, just by the team members working on the tutorial.

You can include some of the following:

• Which pronoun should be used (you vs we). I like the first option better, by the way.
• Keep it simple. A tutorial should not take longer than 30 minutes to complete. It it gets too long, break it up.
• Write short steps. They are more achievable and make the audience feel they are making progress.
• Do not add external links to the steps, they divert users’ attention. External links should be added to the overview section. (Links to the source code, however, are very welcome).
• Add a contact person (a team member) to let your readers know who can they reach out to if they need help.
• Defer material as much as possible. Explain things only when (and if) they are really needed, not before.
• Add screenshots (with captions). Sometimes a picture is worth a thousand words.

Title

• Keep it short and concise (3 to 8 words max).
• Title case is preferred.
• A typical title for a procedural tutorial follows this format: How to <Accomplish a Task> with <Software> on <Platform>
• Provide an example: How to Create a Documentation Project with Antora Running on Docker (sneak peek for one of my future posts…)

Overview

• Here you provide information about the purpose of the tutorial and a definition of the processes, features, etc that will be covered.
• Provide an example: This tutorial is addressed to developers who want to…

What You Will Learn

• Here you create a bulleted list of the takeaways:
  • How to create…
  • How to use…
  • How to configure…
• Also mention which topics will not get covered.

Resources

• You may also want to add internal/external links to provide more information on the topic.
• Use bullets.
• Provide an example: New to the topic? This content will help you get started…
  

Scenario

This section is optional, but I recommend adding it because I think it help users understand more about the context. I found a great scenario at https://docs.microsoft.com/en-us/analysis-services/multidimensional-tutorial/analysis-services-tutorial-scenario?view=asallproducts-allversions and I liked it so much that I use it as a reference in my template. You can always create your own or customize this one to your needs:

This tutorial is based on Adventure Works Cycles, a fictitious company. Adventure Works Cycles is a large, multinational manufacturing company that produces and distributes metal and composite bicycles to commercial markets in North America, Europe, and Asia. The headquarters for Adventure Works Cycles is Bothell, Washington, where the company employs 500 workers. Additionally, Adventure Works Cycles employs several regional sales teams throughout its market base.

In recent years, Adventure Works Cycles bought a small manufacturing plant, Importadores Neptuno, which is located in Mexico. Importadores Neptuno manufactures several critical subcomponents for the Adventure Works Cycles product line. These subcomponents are shipped to the Bothell location for final product assembly. In 2005, Importadores Neptuno became the sole manufacturer and distributor of the touring bicycle product group.

Following a successful fiscal year, Adventure Works Cycles now wants to broaden its market share by targeting advertising to its best customers, extending product availability through an external Web site, and reducing the cost of sales by reducing production costs.

Prerequisites

• Describe the skills needed and infrastructure requirements (don’t forget about versions).
• Be specific. Refrain from using expressions like: familiarity, good command, etc…
• Create a list of concepts that the reader should be familiar with and (optionally, but recommended) provide your readers with resources to get them up to speed in case they need to get acquainted with these concepts to complete the tutorial.
• Provide an example:
  • To follow this tutorial, you need to set up and configure the following…
  • You should know how to create an application with Javascript. For more information, see: <link to external resources>
    

Important Concepts

• This section helps you walk your audience through the tutorial.
• Provide an example: Lets’s take you through the main concepts…

Components

Here you explain the components that make up the feature or application your readers will be working with.

Steps

Here I also add some hidden recommendations (//)

• Provide a checkpoint at the beginning of every step (from the second step onwards). It can be also a link to the source code in your repository. (E.g. Here you can check how your current directory should look like).
• Summarize the progress after every step. (E.g. Congrats! You have just configured…)
• Use admonitions wherever needed.
• If relevant, embed comments into the source code.
• If the step is too long, provide a recap.

Steps Overview

• Overview of the process.
• Provide an example: The following list includes the steps you will take to install and configure…

Steps

The steps are documented here.

Takeaways

Review/reiterate tutorial goals and what your reader has learned.

Next Steps

• Here you can add a link to the next tutorial (if applicable) and/or links to additional resources .
• Provide an example:
  • Read the next tutorial to learn how to…
  • Where to find more information…