How to develop tutorials for software documentation

What is a tutorial?

The primary purpose is to educate users through a step-by-step approach, ensuring they can successfully complete a task or acquire a new skill. Tutorials are learning-oriented and usually tailored to users who are new to the tool or new to a particular topic.

Users should then be able to use their acquired knowledge to use the tool/service further.

Preparing tutorials

  • Who is the tutorial for?

    • Know your audience. If the tutorial is for beginners, ensure that you clearly explain details and provide links to resources that may help them fully understand difficult or new concepts.

  • What is the goal?

    • Know what the users should be able to do at the end. Even better: tell the user what they will learn by the end of the tutorial (e.g. “In this tutorial, you will learn how to do X”)

  • What kind of tutorial do you want to make?

    • What is an ideal format for this tutorial? Should the users follow a step-by-step plain text procedural, or should they be executing code? Would a video be helpful. Visual and auditory elements can be very helpful to provide explanations.

      Keep in mind that tutorials need to be kept up-to-date. Videos, gifs, and screenshots will require revision. Visuals are important but they do need care.

Potential tutorial topics

The most common tutorial is the ‘installation or getting started for beginners’ type of tutorial. But there could be other topics that might be worth looking into.

-Frequently asked questions (not things easily answered by searching the internet).

-Features you want to showcase (see also tutorial-driven development)

Before creating your next tutorial, see if there are resources out there for you to use.

  • Are there any lectures or workshops that use your software? Do they have notes, slides, even an already completed tutorial that you can use?

  • Is there a forum, mailing-list discussion, or issue that contains details that can be used as points in a tutorial?

Contributors and Reviewers

Always try to have other people review your tutorial to ensure it is understandable and covers the topic thoroughly.

  • Subject matter experts - focus on content correctness and relevance

    It is particularly useful to have someone who is not a developer review the tutorial. Often, technical implementation details can sneak into user facing documentation. In research software, an expert in the domain or subject matter of the field can provide content quality assurance.

  • Anyone who might use it - having a potential user contribute to or review the tutorial will provide feedback to how understandable and useful the tutorial really is.

You can also get people who are unfamiliar with the subject; they can test the logic, language, and any technical details.