Tutorial Guidelines - vmware/versatile-data-kit GitHub Wiki

• easy to read
• easy to understand
• easy to replicate

1. Keep it light: Tutorials should be informative and helpful in tone but not overly formal.
2. You, the user: Use second-person pronouns (do use: you, your; don't use: we, I, our, and so on)
3. Keep it short: Sometimes, you must include only the necessary information instead of writing everything about it. Aim for no more than 5 steps and 3 code snippets per page. Paragraphs should ideally be 5 lines or fewer and should deal with a singular concept.
4. Give people easy wins: The frustration is the biggest at the beginning. Therefore, it's essential to reduce friction in tutorials.
5. Be step-by-step: "step one", "step two" sections in tutorials.

Tip: Success needs to be the outcome of the tutorial. This means you must playtest the tutorial under various conditions/systems so that a user with no context can run and test it e2e.
People use the tutorial to understand how the project will “feel” long-term. This means that it should be cross-sectional; a good tutorial should show off different areas of the project.

1. Have focused goals: The first thing a reader looks for in a tutorial is what the tutorial will solve or answer for them. That helps them determine if they're looking at the right article. Before writing the content for your tutorial, establish a well-defined goal you want your users to accomplish. Tell them what problem you are solving, describe the purpose of the tutorial, what value it is providing, and how it will benefit them. Craft your tutorial, keeping this goal in mind.
2. Add estimated time commitment: A new user should be able to experience success within 30 minutes. Roughly estimate how long users can expect to spend on the tutorial. Consider breaking it down into several tutorials if it's longer than 15-30 minutes.
3. Identify the Audience: Clearly state the intended audience for the tutorial right at the beginning. Let the readers know whether this tutorial is meant for Data Practitioners, Operators, Plugin Developers, or Contributors or other more specific audiance. Tailor the content, examples, and language according to the targeted audience. Do not write a single tutorial for multiple audiences.
4. Be upfront: Clearly state any prerequisite that users might need to have set up to work through the tutorial uninterrupted. You should tell the reader which tools, services, and resources you will use for the tutorial.
5. Use graphics: Add supporting images/GIFs and videos. If an image is worth a thousand words, then a video is worth a million. Back your steps by adding graphics.

Tip: for graphics

• Supporting images: Screenshots and images can show the user what the tool or software looks like and where they need to click or type.
  
• GIFs: Show how to navigate through different screens or demonstrate how a process works. Follow the guide How to create a GIF.
  
• Videos: Videos that visually demonstrate the steps and processes for the user.
  
• Diagrams and charts: For tutorials that require a visual representation of data, diagrams and charts can be used to help users understand the concepts better.
  
• Infographics: Infographics can be used to summarize the tutorial’s key points, making it easier for users to recall the steps they need to take. (like the in this tutorial)
  

1. Explain cause and effect: When asking users to carry out a step, explain the reasoning behind the action and the expected result.
2. Tips appreciated: Where applicable, add tips (called out by **Tip:**) to provide users with more intuitive solutions and best practices. You can put Tips in the block quotes as I did in this tutorial.
3. Consistent grammar: Use imperative tense when describing user actions and end sentences with a period. Refer to links: Where essential for context, include supplementary links [link text](link URL) so that users can do their research.

Tip: Make your how-to guide easy to skim. Many people skim instructions. This means that they quickly skip text that includes stories, data, or longer details. People who skim may pay more attention to introductions, summaries, or the first and last sentences of a chunk of text. Bolded, underlined, or highlighted text can also get their attention.

When creating a tutorial, headings are important in determining its structure. To set the correct title, step headings, and underlying instructions, use the following hierarchy:

H1 (#) tags for the tutorial title. There should only be one H1 tag in a tutorial.
H2 (##) tags for a step title.
H3 (###) tags for a sub-step title.
Here is a sample Markdown file you can use to create a tutorial:

# First tutorial

## First step

Hello world

### Part 1

Part one instructions.

### Part 2

Part two instructions.

## Conclusion

Done!

Tip: to making your guide shorter and easier to skim

Use collapsable blocks. In Markdown this happens with <details> and <summary> tags. For example:

<details>
 <summary>Click to expand</summary>
 <p>This is the content inside the collapsible block. You can put text, images, or any other HTML elements here.</p>
</details>

Click to expand

This is the content inside the collapsible block. You can put text, images, or any other HTML elements here.

It's helpful to provide code snippets in your technical tutorials.
This will make sure your readers know what you are doing and what you are trying to achieve with that piece of code.
Also, break down the code into smaller parts, as it will be easier to explain (rather than explaining all the code at once).

Code and terminal blocks should be small enough to read:

1. Aim for 10 lines or less.
2. Aim for 80 characters or less per line to reduce horizontal scrolling.

1. Congratulations: Be sure to appreciate users taking the time to finish the tutorial.
2. Wrap up: Summarize important lessons you'd like users to take away from the tutorial.
3. What's next: Help users along their journey by providing the next steps - these might be recommended reading, supplementary resources, or even another tutorial.

Tip: to make your tutorial:

• easy to read - use the Hemmingway App to improve the readability. Use Grammarly to proofread.
• easy to understand - keep it short and clear. Use simple words and simple terms. Follow the Web Content Accessibility Guidelines. Make the images perceivable - provide text alternatives and captions to your visuals and media. You can test accessibility here:
• easy to replicate - use images to support your tutorial. Save screenshots and create gifs as you go (this will also save you time).

You can find a ready-to-use template for a tutorial Template-for-a-Tutorial

1. Writing Great Documentation - What to write - Tutorials - Tutorial guide
2. Google Tutorial style guide - Best Practices
3. Google Cloud Documentation Guides - Steps - Tutorials, steps, headings, formatting
4. Read the Docs Documentation Guide - Tutorials - Tutorials should
5. How to write a Good Technical Tutorial - Outline for a technical tutorial
6. How to Create a Comprehensive How to Guide [+Examples] - A comprehensive guide to How-to Guides. Highly recommended to read as I didn't manage to include most of what's written there.