This post will cover how to write a post that covers how to do something (so meta!). One of the Agile Roots is to create sharable value so that you, and others, can visualize your learning. I like to model this root by creating tutorials that cover doing things. The wonderful thing about writing these kinds of posts is that I can stay DRY (Don’t Repeat Yourself) by pointing people with questions to the answers I’ve already documented.

Let’s talk about some rules and philosophy behind a good tutorial.

Don’t be esoteric!

We want to write something that will answer questions, not create new ones. Use simple language and spell out what you are trying to say. Keep it simple! Even the use of the world esoteric (which means highly technical speak) here might be a bit much. Pretend that the person reading your post is not a native speaker and has no background in the topic you are discussion. Of course sometimes your target audience might be people who understand esoteric language, in that case go for it.

A picture is worth 1000 words, sometimes

Personally I can’t follow tutorials that don’t have pictures, other people need each step spelled out. It’s wise to use both written and visual media to explain yourself.

Link, link, link

I try to always link to documentation of ideas and technology that support my tutorial but are outside of it’s scope. For instance I was writing about Trello (a web application with cards you can write notes on) and how they use Markdown syntax. I don’t want to go off on a tangent about what Markdown is so I would link to the documentation already provided by Trello.com. If you use a word or introduce a concept that people might not be familiar with, add a link to it’s Wikipeadia page.

Limit the scope

Keep your tutorial on topic and focused on a single issue. It’s easy to go down a rabbit hole and start explaining a bunch of stuff that is related to the thing you are talking about. Use your best judgment to determine if what you are talking about is adding or distracting from your main topic.

Let’s Make a Tutorial

Start off with an introductory paragraph. I like to relate the tutorial with a real life story or some personal anecdotes like I did at the top of this page. Don’t make it too long though, people are here to learn about a specific thing and probably don’t want to wade through more than a few sentences.

Create an Outline

Your outline should go over the broad steps involved, think of this as a quick reference that leads into more detailed steps:

• Introduce Tutorial
• Provide an outline
• List needed materials
• Collect screenshots/pictures of a “example run”
• Edit screenshots with text, arrows, and removal of sensitive data
• Create post with a descriptive title
• Write the body content, make use of headings
• Write a conclusion, ask for feedback

Material list

Before you get into the meat of the tutorial make sure you list the supplies someone will need. These will obviously be wildly different depending on the tutorial. Here are some ideas:

• A camera to document the process, perhaps keep a sticky note near the project space that says “take pictures!” to remind you to photograph each step
• A note pad to record each supply use use
• A voice recorder or video camera
• A place to record the tutorial, like a blog.

Screenshots & Pictures

I typically go through the steps of the tutorial I’m writing before I write the tutorial so that I can collect screenshots. If you are doing something in the “real world” make sure you have a camera ready and are taking shots. Really think about details that people will need to know when doing the thing themselves. Be aware of knowledge that you take for granted.

For instance I often will say something like “click the menu button” and forget that the menu button is small and out-of-the-way. A newbie might have a hard time finding that. A better way to say that would be “click the menu button in the top right corner of the page” and better yet, add a picture:

Taking Screenshots

If you are writing a tutorial about something that happens on a screen you’ll probably want to capture the action on your screen.

I will be going over some techniques for taking screenshots on a Mac, if you have Windows or Linux or a tablet, please refer to take-a-screenshot.org

I prefer to use Mac’s partial screenshot function so that I can take a picture of only the important section of the screen (Tip: don’t crop too tightly or you might lose context for the screenshot) This is achieved using Cmd⌘ + 4 which then provides you with a little crosshair. Click, hold, and drag the crosshair to form a box, once you release the mouse button the screenshot will appear on your desktop.

Adding symbols and text to picture

Sometimes you’ll want to direct attention to a specific spot on your picture, symbols (like the arrow) are great for this! Again, I’m only going to show you on Mac, you windows folks will have to use MS Paint or something (sorry).

On Mac OSX: Once you take the screenshot open it in preview.

Expand the edit panel:

Then use the line tool:

You can adjust the line tool settings on the right , by setting the arrow head on the left the arrow head will appear where you start your line which I find gives me more control.

Remember: Be aware of what you are taking pictures of, you don’t want to inadvertently share a secret password or email address in your public tutorial!

Now save the picture and you’re ready to post it!

Create the post

Coming up with a good title is very important, you’ll want to the title to reflect what you are going to be talking about. This is how people will search and find your awesome tutorial so take some time to think about it!

Remember, also, that the title and first 150(ish) characters will appear on search results and social media posts, so make it count!

Using headings

As you can see from this post I’ve made use of headings to break up the content. Typically each heading has a size (or level). For instance “Lets make a tutorial” is heading 1, then then main points are Heading 2 (e.g. “Create the post”) while sub headings like the one directly above are Heading 3.

This is simply good practice for formatting posts. You can imagine this post (up to this point) has a nested outline like so:

• How to Make a Good Tutorial (title h1)
  • Don’t be esoteric! (h2)
  • A picture is worth 1000 words, sometimes (h2)
  • Link, link, link (h2)
  • Limit the scope (h2)
• Let’s Make a Tutorial (h1)
  • Create an Outline (h2)
  • Material list (h2)
  • Screenshots & Pictures (h2)
    • Taking Screenshots (h3)
    • Adding symbols and text to picture (h3)
  • Create the post (h2)
    • Using headings (h3)

See how clear this outline is? Doing things this way isn’t necessary but it does create a data structure that eventually will come in handy when humanity (possibly) moves to the Semantic Web in the future.

That’s it!

Now we are done with the tutorial. I typically like to write up a short conclusion about the great things we’ve learned, like how to take screenshots and edit them and how to use headings and break up your tutorial.

Have any questions? Or comments? Leave them below!