Useful Formatting Tips

It's important that every tutorial we publish looks fantastic. This page highlights how we deal with headings, images, videos, quotes, and code. By following the below examples, you should be able to make your tutorial look perfect!

The Style Guide

A good place to start when thinking about formatting to use is our style guide. This will give you a good understanding of the high-level requirements for written content, before you delve into some of the specifics below.

Italics and Bold

We have a few simple rules for when to use italics and bold, and we stick to them wherever possible:

  • Use bold for anything you read on either the screen or keyboard (e.g. “press Alt-Shift-N", "click File > New", "the Layers panel").
  • Use <code> for code keywords and anything you type in (e.g. "set the colour code to #2886c8", "use a for-each loop", "give it a name of confirm_button").
  • Use italics for adding emphasis to actual text ("whatever you do, do not click the Delete button").

Working With Images and Files

Naming Images

You'll need to choose a sensible naming style for your tutorial images. We recommend using the tutorial name, then a brief description of the image. For instance, if your tutorial was about creating a button in Photoshop, you might use:

  • photoshop-button-creating-canvas.jpg
  • photoshop-button-background-color.jpg
  • photoshop-button-final-product.jpg
  • etc...

Or, if your tutorial was about creating crafty easter decorations:

  • easter-decorations-supplies.jpg
  • easter-decorations-fold-in-half.jpg
  • easter-decorations-first-triangle-fold.jpg
  • etc...

Image Captions

Sometimes it can help to explain an image with a caption sentence. You should only use a caption if it adds something to the image. Don't simply describe what the image contains, or use a generic caption such as "Figure 1", "Image 1", etc. Captions shouldn't be used for referencing an image source — instead, place all image sources in a bulleted list at the end of a tutorial.

Alt Text

Each image you upload should be given "alt text". This is the text that will show up if the image is unavailable (or if images are turned off, and someone is using a screen-reader for instance). This should be a very short description of what the image depicts - no more than ~100 characters.

To add alt text, click your image after uploading it, then type the text at the top left of the image in the box that appears.

Embedding Images

We have a simple tool in our CMS for uploading images. When creating your post, just click the "Insert Image" icon, then select one or more images. You can upload multiple files at a time, but don't forget that you'll need to resize images to 850px wide on your computer before uploading.

The image will then be added into your editing window, within the tutorial you're writing.

Adding Other Files

Occasionally you'll need to upload a different file (such as a set of resource files for a tutorial, a code demo, or a PDF). You can attach this file by using the "Attachment" box on the right. Click "Choose File" to upload your content.

Capitalisation

We have a specific way to capitalise headings — both post headings, and sub-headings within a post itself. You can use our own mini web app to do this, which will ensure each heading is capitalised correctly.

Actions & Steps

Some tutorials are simplest to follow when broken down into a series of actions and steps (particularly when you're asking a reader to follow along as you create something). Here's the best way to structure this type of tutorial, with "main" steps, and then "sub-steps" within them:

  • 1. Create the Base of the Button
    • Step 1
    • Step 2
    • Step 3
  • 2. Adding Layer Styles
    • Step 1
    • Step 2
    • Step 3
    • Step 4