Style Guide

Overview

Teaching: 10 min
Exercises: 0 min

Questions

• What style should be used for Carpentries lessons?

• How are keyboard key combinations written?

• How are short spans of code written?

Objectives

• Explain keyboard key combination.

• Locate documentation for general matters of style in The Carpentries.

• Identify uses of the span of code Markdown feature.

This episode contains lesson-specifc style guidance and related implementation details related to The Carpentries lesson template. For more general matters of style, see the The Carpentries Style Guide.

Emphasis

Markdown treats asterisks (*) indicators of emphasis, and renders text marked up like this in italics. We use emphasis

• to highlight a word, phrase, or character where it is itself the object of discussion.

  For example,

  We want to output the lines that do not contain the word *the*.
  

  This is preferable instead of the use of quotation marks.

  See the “Keyboard Key” section for characters or keyboard keys that the learn should type.

• for words and phrases that are still regarded as unfamiliar.

• for titles of books, periodicals, plays, films, TV, radio series, and music albums.

  For example,

  We will use a file that contains three haikus taken from a 1998 competition in *Salon* magazine.
  

Strong Emphasis

Markdown treats double asterisks (**) as indicators of strong emphasis, and renders text marked up like this in boldface. We use strong emphasis

• to highlight a newly introduced term, often one that is going to be defined or explained. For example,

  We are all familiar with **graphical user interfaces**
  

Span of Code

Markdown treats backtick quotes (`) as indicators of a span of code. We use span of code

• to highlight part of some code where it is itself the object of discussion.

  For example,

  For example, `range(3, 10, 2)` produces
  

• to highlight one command where it is itself the object of discussion.

  For example,

  you can run it by opening a terminal and typing `bash`.
  

  When the object of discussion is the program or language in a broad sense, we don’t use span of code. For example,

  The most popular Unix shell is Bash.
  

• to highlight one function where it is itself the object of discussion.

  For example,

  `len` is much faster than any function we could write ourselves.
  

• to highlight one file name where it is itself the object of discussion.

  For example,

  `my_file.txt` can also be viewed in your GUI file explorer.
  

• to highlight any sequence of character that the user is expected to type.

Keyboard Key

When making reference to a keyboard key that the reader should press the HTML tag <kbd> must be used to enclose the key label. For example, “to delete the cell press D” should be written as

to delete the cell press <kbd>D</kbd>

The table below covers most of the keyboard key labels.

Keyboard Key Combination

When making reference to a keyboard key combination that the reader should press, insert a plus sign without space between each one of the keys. For example, “press Ctrl+X to quit nano” should be written as:

press <kbd>Ctrl</kbd>+<kbd>X</kbd> to quit nano.

Links

Please label links with meaningful texts, in order to improve accessibility. Please avoid click here or similar.

Menu Items

Use double quotes for menu and submenu items. For multiple menu and submenu options in a sequence, use the right angle bracket or greater than sign.

e.g.:

“Help” > “Check for updates”

Title Casing

Lesson and episode titles should be written in title case e.g.

Saving the World, One Commit at a Time

An exception should be made where the title includes the name of a tool/library/command that must be typed in lower case when used, e.g.

Data Visualisation with matplotlib

(In HTML files, such as the workshop schedule and syllabus files in the workshop webpage template, tool/command/library names such as matplotlib in the example above can be correctly formatted using <code></code> tags.)

Key Points

• The Carpentries Handbook contains a style guide.

• Keyboard actions are described using the <kbd> HTML tag.

• A backtick (`) indicates a span of code and is used to enclose code excerpts, segments of text to type, and filenames within in narrative text.