How to Format Semaphore Tutorials for Publishing
Guidelines for formatting the text of Semaphore community articles.
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.
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.
Each source line of the tutorial should be limited to 80 characters or less. The only exception is when a line includes a link with a long URL.
This section explains how to use headers in your tutorial.
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.
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.
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.
The first section of every tutorial should have an H3 header Introduction, followed by a paragraph or more 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.
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.
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 formatting should be used for:
- Code snippets
- Files and scripts
- 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 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.
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 > email@example.com 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
- Package names, like
- Function names
- File and directory names, paths like
- Options like
- Method arguments like
- Example URLs like
- Ports like
- Key presses like
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 should use the standard Markdown link style with no extra formatting. Use unordered lists to emphasize or group similar resources.
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 745x745 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.
Follow these conventions when writing regular text:
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 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.
Most of the time, you'll want to use an unordered list. They’re great for:
- 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
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.
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.