Tutorials and Walkthroughs

When the integration steps of your project are not immediately apparent to a junior developer (this applies to almost everyone), write a tutorial or a walkthrough. This type of material explains how to accomplish a prototypical implementation of your project by guiding the user through it step-by-step, often with the use of code snippets.

Writing Walkthroughs

The first step to writing a walkthrough is asking yourself the following questions:

What will this walkthrough show the user how to do?

Write a title like "Use Express.js with Mongoose to write a REST API" or "Use Inquirer.js to create a command-line todo app". List the major libraries or frameworks that the walkthrough is about in the title. Make sure to mention what the intended result will be.

What is the technical level of the audience?

The answer is "A Junior Developer". Most of the consumers of walkthroughs are junior developers. Senior developers read walkthroughs as though they're very detailed Quickstarts, or to figure out what an idiomatic design pattern is for an environment they're unfamiliar with. Everyone reading a walkthrough needs guidance through the task at hand, so it's safe assume the reader is not familiar with your environment.

However, in most cases, it is also safe to assume the reader can program. Assuming the reader can program in the language the walkthrough is written in is also a safe bet. Linking at the top of your walkthrough to some helpful materials to learn the language will cover all the cases where someone brand new has landed on your tutorial. No one who knows how to program wants to read about how if statements work in your REST API walkthrough, nor will someone brand new to if statements be able to understand your REST API walkthrough. Make explicit assumptions about the reader's level of technical knowledge, and then stick to those assumptions.

What environment / technologies do I assume the user understands?

You must list these near the start of the document. If you assume the user understands MongoDB, link to the MongoDB Documentation. If you assume the user is familiar with the entire stack your company uses, list each element of your stack.

Integrating and assuming the fewest possible number of technologies is a best practice. If your library is set up to use CSS3, LESS, and SASS, but your walkthrough is actually about how to serve dynamic templates and there's a small section where you use SASS once in one part, don't make the user install and configure SASS, use CSS3, no matter how much "easier" or "more elegant" the code examples look to you. Use the most popular, widely understood option; your goal is to minimize the burden of what the user must understand before they can use your walkthrough, otherwise you will severely limit your audience.

What to write first?

The order you should write your walkthroughs in:

• Quickstarts
• Most common / first intended use case
• Integrate with one other commonly used system or framework
• A full-stack application
  • Has a view
  • Has persistance
  • Demonstrates some arbitrary business logic
• Full-stack applications in different languages
• Walkthroughs demonstrating integrations with widely used (but not the most widely used) systems or frameworks

When should I use a Demo?

Use a Demo when you:

• Don't have time to write a walkthrough
• Are showing a complex design pattern that would have users interacting with more than 5~7 files
• A running system would be far more illustrative than building the system from scrach
• To appeal to senior developers

All walkthroughs should feature a link to a running demo.

Maintaining Walkthroughs

In short, you must maintain a review cadence on your walkthroughs. Set yourself a google calendar reminder for every 6 months.

When you write a walkthrough and release it to the world, you probably check on it for the first few weeks to see how it's received, but after a year you likely don't think about it. 10 years later, your walkthrough may happen to be the top search result for one of the most commonly used features of a framework that hundreds of thousands of apps use- you want that result to give a good impression of it's author, right?

Check up on your old walkthroughs. After you release it, set a recurring reminder to check on it every 6 months. The 2 hours you spend updating it some years down the road may save thousands of hours of developer time across the industry, not to mention netting you a great reputation. New developers encounter old technology all the time, often after older versions of documentation are no longer available.

Checklist

• Assumptions about what the reader knows are explicitly stated at the top
• Title indicates what major libraries and frameworks are used
• Title indicates the result of the walkthrough
• Walkthrough assumes a consistent level of technical expertise
• Instructions are followed by complete code snippets
• Code snippets all have the filename they are intended to reside in listed at the top
• Code snippets all feature line numbers
• Code samples all work when copy-pasted
• Packages and frameworks include explicit versions (otherwise the walkthrough will decay rapidly)
• Technologies used are the most widely-adopted
• Features the fewest number of integrations possible
• Provides a link to a version controlled working copy of the finished code (or a zip file)
• Version controlled working copy uses branches for multiple stages
• 🌟 Walkthrough is cross-posted on the author's blog for posterity

🤓 The word tutorial is defined as "a period of instruction given by a university or college tutor to an individual or very small group." A walkthrough is defined as "a tour or demonstration of an area or task." The context most programmers think of a tutorial in is "a detailed step-by-step guide detailing how to accomplish a task", meaning the two terms are used interchangeably in the world of programming. Not that it matters, but the technically correct term to use for this kind of material is "Walkthrough".