How to Format Semaphore Tutorials for Publishing

Introduction

This article explains how to format Semaphore tutorials. By following the details in this guide and the companion Style Guide, your tutorial will match all of the Semaphore guidelines.

Where can I submit the completed tutorial?

If you have an approved writing sample and topic, you can submit the tutorial as a link to a gist, or as a .txt or .md email attachment.

Where can I submit a sample?

If you don’t yet have an approved sample and topic, follow this link to become a Semaphore Community author.

Markdown

Semaphore tutorials should be formatted in the Markdown markup language.

While this article lists some examples of Markdown applied to writing a tutorial, for a more comprehensive Markdown guide refer to Daring Fireball.

File Formatting

Each paragraph should be one line in the source Markdown, as this helps adding suggestions during the review process.

Headers

This section explains how to use headers in your tutorial.

Title

The tutorial should begin with a title using an H1 header, and it should be the first line of your file.

For procedural tutorials, the title should begin with How to. The typical title should follow the format of How to do Task with Tool and AnotherTool. For example, How to Deploy Sinatra Applications with Capistrano.

For introductory tutorials, the title should begin with Getting Started with, e.g. Getting Started with Node.js and Jasmine.

In other cases, try to formulate the title using the gerund (-ing words) and a phrase that summarizes what you are teaching the reader to do.

Header Formatting

When writing any title, prefer Markdown’s “hash marks followed by a space” (## ) over the underlining syntax.

Do not use special formatting, such as links or code blocks, in headers.

Capitalization

All headers in the tutorial should be written in title case, as described by the Chicago Manual of Style:

Capitalize the first and last words of the title and all nouns, pronouns, adjectives, verbs, adverbs, and subordinating conjunctions (if, because, as, that, and so on). For example: Rules for Capitalizing the Words in a Title.

Articles (a, an, the), coordinating conjunctions (and, but, or, for, nor), and prepositions, regardless of length, are lowercased unless they are the first or last word of the title.

When in doubt, use titlecapitalization.com to do the capitalization for you.

Introduction

The first section of every tutorial should have a paragraph or two describing the goals, methods, tools and results of the tutorial.

Typically, the introduction should cover:

• Main topic of the tutorial.
• What the reader will learn from it.
• Methods to be applied and all tools involved.
• What the reader will have accomplished or learned at the end of the tutorial.

Prerequisites (Optional)

Introduce your prerequisites with a sentence or several paragraphs, as needed. Then, include all of the required items, software, and configurations as separate list items that the reader can use as a checklist.

Common prerequisite bullet points include:

• Link to a tutorial about installing prerequisite software, such as Grunt or a sample application.
• Link to a source code repository that the reader should clone.
• Link to part of a tutorial, e.g. Follow the steps from this tutorial to set up RSpec.

When you link to another Semaphore tutorial as a prerequisite, make sure that in preparing your new tutorial, you follow all the commands from that other tutorial yourself.

H2 Sections and Related Descriptions

Every header must include at least one sentence under it that describes the context or purpose of that section of the tutorial. Don’t jump from one header to another. Here’s an example of a good mix of headers and explanations:

Setting up a Sample Project

In this section we will set up a simple application which will serve as a starting point for our custom Kerodon matcher.

Prerequisites

For developing Clojure applications you need to have a Java JDK version 6 or later.

Also, do not start a section with a contextless instruction or command. Instead of:

Create a Compojure Application

lein new compojure kerodon-tutorial

You could write the following:

Create a Compojure Application

Leiningen provides a Compojure template that allows us to get started with Compojure quickly.

Create a Compojure-based Clojure project with the following command:

lein new compojure kerodon-tutorial

Use of Subheadings

You should be able to format your text using only H2 and H3. H4 should be avoided.

Code

Code formatting should be used for:

• Code snippets
• Files and scripts
• Commands
• Output
• Interactive dialogues
• Inline items, as explained in the section below

Every code block needs an explanation. The sentence(s) must describe what the code block does, and end with either a period or colon. Examples of good explanations:

• Start by creating an empty Node.js project.
• At this point, your project tree should have the following structure:

After a code block, you should always start with a new sentence.

Code Snippets

Code snippets should be formatted with three backticks, followed by a language identifier whenever possible, as in the GitHub Flavored Markdown. This will ensure syntax highlighting of the code, for example:

` ruby
# app/helpers/users_helper.rb
module UsersHelper
end
`

Note that it is sometimes helpful for the reader to include the name of the file as a comment in the first line of the code snippet. This is useful when covering frameworks which have certain conventions, and spelling them out for multiple files could blur the point of the tutorial.

Commands

Any command that the reader needs to execute to complete the tutorial should be in its own line, not in-line, and it should be formatted with a code block.

Remember that every command needs an explanation. The sentence must describe what the command does. For example:

Install the [Express.js](http://expressjs.com/) framework:

` sh
npm install express --save
`

Always describe options and flags which the command is using.

Do not show the command prompt for Bash or similar shell. However, if your block includes both the command and its output, then do use the command prompt:

$ npm test
> hello_world@0.0.1 test /home/igor/hello_world
> jasmine-node spec

FF

Finished in 0.007 seconds
2 tests, 0 assertions, 2 failures, 0 skipped

You can group commands that are covered by the same short explanation. For example, it’s OK to group commands to create and then change to a new directory.

mkdir hello_world
cd hello_world

In all other cases, commands should be written in separate code blocks and have their own explanations.

When to Use Inline Code Formatting

In-line commands are useful for referencing:

• Command names, like mkdir
• Package names, like rbenv
• Function names
• File and directory names, paths like app/hello_world.js
• Options like -latr
• Method arguments like filename
• Example URLs like http://example.com/myapp
• Ports like :3000
• Key presses like ENTER

Don’t use inline code for commands the reader needs to execute. Also, don’t use it to emphasize something – use bold formatting instead.

Links

Links should use the standard Markdown link style with no extra formatting. Use unordered lists to emphasize or group similar resources.

Images

Images should use the standard Markdown image style. Please include descriptive alt text, so that readers using a screen reader can rely on the alt text rather than the image.

![Alt text for screen readers](/path/to/img.png)

Guidelines for images:

• Use the .png file format.
• Max size of 745×745 pixels.
• Make the image with as short a height as possible.
• Host images on imgur – Semaphore editors will take care of uploading the images to our servers.

Types of images that can be used:

• GUI screenshots
• Technical diagrams

Please do not include images of console output. Commands and output should be included as code-style text so they can be copied.

Text Styles

Follow these conventions when writing regular text:

Bold

In general, use it sparingly. Here’s a list of items that should be in bold:

• Note: and Warning:
• Breaking up article sections (see the beginning of this article).
• In a term list, e.g.:
  • Request: HTTP client
  • Express: web framework
• Any items the reader shouldn’t miss, but please don’t overdo it.

Italics

Italics should only be used when introducing technical terms, important concepts or book titles. For example, a Ruby expression can define an expectation on a piece of code.

Lists

Most of the time, you’ll want to use an unordered list. They’re great for:

• Prerequisites
• Checklists
• Terms and explanations
• Listing additional resources.

Referring to Tools and Software

Use the official capitalization of the software name from its website if available. If the product website is not consistent, please be consistent within a single article and favor capitalizing the first letter. For example, Node.js or Vim. Be sure to honor acronyms, like SSH.

On the other hand, you don’t need to capitalize commands and package names. For example, a JSON payload string can be parsed with Ruby using the json gem.

The first time you mention a software tool which has its homepage or open source repository, always make it a link to that web page.

Conclusion

Do not end the article abruptly. Write a brief conclusion for your tutorial to summarize what has been accomplished, and what the reader might want to do or read next.

That’s it! Check out the Style Guide, and you’re ready to start writing your Semaphore tutorial. Happy writing!