The Internet started as a publishing medium. It excels at enabling people to share their unique gifts. An amazing amount of content gets put out on the web everyday, far beyond someone can read in a lifetime. Massive amount of information also means information overload.

In software, it is common to use web tutorials to supplement one’s learning of a particular material. Following guidelines of someone who has already done it can really fast track development. Tutorials appear in various forms in the web. Some of the common formats are long form blogposts, videos and series of email newsletters. Some enjoy the personal touch that videos can offer; others enjoy being able to quickly skim a blogpost.

When you want to put your hard earned knowledge and valuable time into writing a tutorial, there are questions worth thinking about. Does the tutorial cater to its intended audience? Will it reach them? Can someone quickly skim the content and still get value? Is there a way to measure the effectiveness of online tutorials?

To look for answers, I asked a carefully selected group of 150 people about their preference of tutorials. The focus was on software engineers/designers/entrepreneurs due to my familiarity and experience with the field. What emerged from their responses gives a blueprint for creating great online resources.

1. Real time feedback: If exercises or examples accompany a tutorial, multiple survey responders emphasized the need to check the user’s responses and provide interactive feedback to the user to guide them to the solution. Good examples are checkpoint multiple choice questions during Coursera/Udacity courses that you must complete to move forward with the course.

2. Follow up: Several responders emphasized the need to provide contact information or other means to reach out to the author once they went through a tutorial. Providing a comments section or your email/twitter handle are great mediums for a reader to follow up.

3. Address a concrete problem: Staying focused of a specific problem gives a tutorial depth. A differentiator can be to classify for the user whether the focus is academic and structured vs. a blogpost focused on solving a particular problem right now.

4. Working examples: Interactive, working examples close to the content that builds on top of each other makes following along simpler. Michael Hartl’s Ruby on Rails tutorials came up as an example of detailed, comprehensive tutorials.

5. Advanced user tutorials: Several user’s pointed out the need for tutorials that addresses advanced content. Making expectations clear about experience levels of intended audiences can be a huge positive for tutorials. Ray Wenderlich’s iOS tutorials are good examples of the detail and level of research and understanding that can happen before putting out content on the web.

1. Copyright: Sometimes an afterthought, it may be worth pointing out what license the content is released under. This can give the reader’s clarity on how to attribute the source when they use that content in production. Github makes this really easy with license options provided during repository creation.

2. Offer tangible short-term benefits: While this certainly applies more to blogposts rather than courses, focusing on offering user’s value short, medium and long term can improve the message of a tutorial. Moreover, an user may be more inclined to follow through the entire content of a tutorial if they are get that value at different stages of the tutorial.

3. Timeliness: This could be hard to measure, but popularity of tutorials can be attributed to how current and relevant they are. As of the time of writing this blogpost, April 2016, there are lot of people looking to get into VR/AR, chatbots, AI and so on. Accounting for recency can certainly increase the reader counts of your posts.

4. Continuity: It became clear through the responses that while people looked for tutorials to solve a particular problem, they return because they are looking for a subject matter expert. Producing a series of tutorials taking on different aspects of a topic can help with retention.

5. Discoverability: This can go in the realms of SEO, but lot of responders responded to their favorite source of online tutorials with well-known sources. Coursera/Udemy/Khan Academy/YouTube and Google were all common ways people went around in finding online tutorials. If you do not want to solve distribution for the content you create, writing for more known blogs/sites can be a way to reach larger audiences.

6. Formatting: A big part of the user experience, proofreading cannot be left for the last. In the tech space, prominent writers such as Paul Graham always attribute at the end of the blogpost all those who have helped proofread the content. Just passing it around to a few people before publication and basic spell checking/grammar checking can improve the user experience for tutorials.

There are definitely caveats to this survey. As the person compiling this survey, it is at least slightly influenced by my biases. My target group is highly technically literate, so there is a bias towards modern tools. Perhaps it is worth taking into account the intent of writing tutorials, be it teaching, lead generation or growing a business.

Like most studies, this too should be taken with a grain of salt and in no way is sure way to produce great tutorials. Someone’s genuine passion, interest and the willingness to learn and teach find their ways to shine through content. However, just as the Joel Test for Software Development companies is often a good checklist for expected standards of software companies, being aware of the reader’s needs and voice can lead to sharper, more helpful tutorials.

Research for this post was done by using Dripper, a twitter direct message automation tool that I helped build. Feel free to reach out if you want to know more about the software!