I was asked this question a few weeks ago and honestly did not have a great answer.
I've always considered them to be interchangeable terms. After some digging, I discovered the Diátaxis framework which seeks to create structure around the way developer educators...educate developers...
The big difference is in their goal
The goal of tutorials is to help the reader understand the concepts of something in a safe environment.
The word originates from "tutor" which is a pretty good indication of how these docs are to be used. I suspect that most technical writers (myself included) typically write tutorials for their content.
The goal of a guide is to "guide" the reader to an end goal in the real world. albeit still safely.
They are rarely as clear-cut as tutorials since they have to adapt to real-world environments. But they are extremely valuable to readers trying to get something done.
What to do with this information?
Understanding the distinct goals between these two will help in crafting the content for users for their desired outcome.
Tutorials should provide as many samples as possible, and guide the reader to understand the concepts. Personally, I love to provide a repository that has separate branches for a start point and end point. The article itself walks the user through the process of getting to the endpoint, step by step, but they can look at the solution at any point in time.
Guides should cover as many edge cases as possible to help the user get the results they need in their projects. I've traditionally only written guides with more direct and dry language, however, I plan to start addressing edge cases for readers much more.
Top comments (0)