Tutorials: What, Why, When, How

by ya #1 wordsy boi, Ed Prosser

We're going to cover:

what is a tutorial

why we use them

when we should use them

how we should use them

In general, we break content down into three broad types.

Concepts

• Concepts are always informative, rather than instructive. They have no gerunds (effing, blinding, infuriating words)
• Concepts have the broadest range of audiences, from the very general "Introduction to Composer" to the very narrow "Fabric Transaction Lifecycle: A treatise in 90,000 words".

Tasks

• Tasks are always instructive. They are gerund central. Installing, upgrading, deploying, destroying, deleting, complaining, and sacking are all good task topic beginnings.
• The point is that they help a user get from point A to point B in terms of a task, function, or objective. They are specific, and preferably actionable by one person.
• Good examples of tasks: Installing Hyperledger Composer, Using Google OAUTH2.0 with the Composer REST server.

References

• References are for technical information, they shouldn't be required reading for following the rest of the documentation, but will likely be required for building a custom solution.
• API documentation is a good example of a reference document, as well as command lists.

Where do tutorials live in this scheme?

Well it depends on the tutorial.

Tutorials are somewhere between a concept and a task.

What makes a tutorial:

1. Tutorials have a learning objective. They exist to teach something, rather than a task's functional objective (to do something).
2. Unlike a concept tutorials are not theoretical explanations of a concept. Unlike a task, tutorials are relatively broadly scoped.
3. Tutorials serve as an example. They are there to guide, but not to instruct, users on how to structure or develop their own projects.
4. They include not only steps to follow, but also explanations on why those steps are being taken.

Tutorials are useful for a number of reasons:

1. People learn by doing.

When there are a lot of cliff edges to fall off, providing a tutorial that includes best practices and a general use-case or example gives the reader a good place to work from.

2. Tutorials often require minimal context.

When writing a tutorial, it doesn't matter what the reader's specific business use-case is. For example, whether you're tracking containers or building cars, understanding the access control language is just as useful*. This is a major differentiator from a task. Tasks are very specific in their positioning, as you can see in the following example of a table of contents.

3. Tutorals set a precedent.

Tutorials set a precedent for future behaviour. We tutorialise the 'golden path' generic behaviour we want users to replicate.

When we need a tutorial can sometimes be hard to define:

1. When dealing with complex infrastructure or surrounding technologies.

Some of the Composer documentation is a great example of adding tutorials to the golden path. We cover getting to grips with the composer modelling language, organisational tutorials (single and multi-org), and an introduction to the access control language.

2. Tutorials are very useful when we expect a near-infinite number of customer use-cases.

When there are too many potential task topics to begin considering writing, we can be forced to cover the gap with tutorials. By writing tutorials, we can outline the best practices in a simple environment, and advise users to follow our example when building their own solutions.

3. When we need to explain something quickly, or provide understanding in a fixed real-world context.

Getting people up to speed quickly is difficult in a task topic. Tasks are focused on completing the functional objective as efficiently as possible, whereas if understanding is the goal, tasks can often leave the reader behind. Great examples when tutorials can help are: hackathons, client workshops, demos, and proof-of-concepts.

Luckily, having defined what, why, and when we use tutorials, how to use them is quite simple:

1. We use tutorials to give our users the knowledge to make something themselves.

2. We use tutorials to set a good example to users.

3. We use tutorials at key points in a user's development lifecycle.

Tutorials are:

Topics that have a learning objective over a functional objective, use examples, and explain why each action is taken to teach the reader how to implement a system or process.

Tutorials are good because:

By following a process topic with a learning objective, the reader is engaged in the activity, as well as reading about it. Tutorials are more general than tasks, affording them a lower barrier to entry, whilst imparting information to the user in the form of reinforcing the 'golden path' we want them to take.

We use tutorials when:

When we have an agenda on the information we want our users to learn, especially when complexity can lead them astray, or when we can't account for all the potential scenarios the user might have. Tutorials are also useful when we need to priotise the understanding of the reader over any functional objectives.

We use tutorials by:

We use tutorials by choosing the roadmap for users to follow, giving them the information for them to plan their own route, and placing tutorials as signposts at different stages of the expected development lifecycle.

Bonus slide!

There are also things which harken back to the old IBM-Information-Development days called 'Scenarios'. Scenarios are more like a compilation of tasks with tutorials all involved in a specific suite of tasks, that cannot be divided from each other without losing necessary context.