This is a work-in-progress guide to writing and formatting content for LaunchCode education programs.
For general grammar, style, and punctuation guidelines not covered here, refer to the Purdue Online Writing Lab (OWL).
For headings, use title case (all major words of the headline capitalized). For the definition of “major word” we defer to AP style:
Capitalize the first letter of every word except articles, coordinating conjunctions, and prepositions of three letters or fewer. There’s one exception: Any word that is the first word in the headline or the last word should be capitalized, regardless of its part of speech.
Every page should begin with a level-1 heading, and heading levels should never be skipped. For example, do not use a level-3 heading below a level-1 heading without a level-2 heading in between.
Use headings to segment content by topic. Do not use headings for emphasis.
Headings should also enable easy reference. When writing a heading, consider how well it describes the section’s contents. If a reader saw the heading in a table of contents, would they have a general idea of what it contains?
Quotes have semantic meaning, and should therefore be used only in specific circumstances.
The most obvious usage is to include a verbatim statement by another person or entity. In the case of a rhetorical or hypothetical statement, use italics.
Ryan said, “I used to think less was more, but now I’m thinking more is more!”
The only other proper use of quotes is to refer to a word as an object within a sentence.
When it comes to words, “circumlocution” is one of the best.
When using quotes in this way, all punctuation goes outside the quotes.
Finally, when writing curriculum you should avoid using scare quotes. Scare quotes are quotation marks used around a word or phrase intended to signal irony or derision.
The Internet is built on HTML, a “programming language” introduced in 1993.
The use of scare quotes is overtly colloquial and can be confusing. If tempted to use scare quotes, rethink what you want to convey and find a way to do it without them. Not convinced? Read a few reasons why scare quotes should be avoided.
In all cases, use double quotes unless including a direct quotation that itself includes a quote.
Formatting for Emphasis¶
To call attention to a sentence, phrase, or word within a paragraph, you may use italicized text.
It is also acceptable to use all-caps to emphasize text. However, we prefer italics over all-caps in most situations, and all-caps should be avoided for phrases and sentences.
Finally, italics and all-caps should RARELY be used to emphasize the same content.
Formatting for Semantic Meaning¶
Formatting may convey additional information about a word or phrase. This is what we mean by “semantic meaning.”
When an important term is first used and defined, format it in bold.
A function is a callable, reusable piece of code.
In the majority of cases, you will only bold a vocab word the first time it is used. On occasion, it may make sense to bold the word a second time, at a different location, if it is being reintroduced in a new way.
Application and UI Labels¶
Format labels for application menus and other UI components using italics.
To open a file in Atom, use File > Open.
The following section uses Markdown syntax. The same principles apply for RST, but with the corresponding syntax. See the RST section below for info on how you should format code segments in RST.
Fenced code blocks¶
For code segments more than two or three words long, or for those that
warrant calling the user’s attention to, use triple-backtics
`) or triple-tildes (
~) to create a fenced code block.
Add the language in question just after the opening triple to enable
```java public static int counter; ```
We prefer backtics over tildes; however, tildes should be used when it is necessary to include triple-backtics within the block itself.
Some common language identifiers supported by Pygments are:
sql. A full
list of supported languages is
available. To find the language identifier for a supported language,
refer to the “Short name” property of the language’s lexer from the
full list of Pygments lexers.
For terminal/shell commands, no language identifier is used:
``` $ javac Hello.java ```
Shell commands displayed in block style should include a generic prompt:
\$. Shell commands displayed inline (as below) should not be
For short segments, or individual code words, enclose in single backtics:
The `static` keyword in Java is used to...
You should always enclose the following types of types of items in single backtics:
Programming language keywords, symbols, and identifiers
File and directory names
URLs referenced literally (i.e. not linked)
For inline code that contains a backtic, use double backtics:
There is a literal backtic here: ``(`)``
One exception to this rule is when any of these elements appears in a heading. See the Headings section for details.
For headings, the hierarchy of characters underlining text should be:
.. code-block::are synonymous directives for creating fenced code blocks, but we prefer
::to format unhighlighted literal blocks, place the
::on their own line.
Use double backtics to surround inline code segments:
For ordered lists, use
#.over numeric item labels like
.. image::since the former has a richer set of options.
Use the Oxford comma!
Use a single space after end-of-sentence punctuation!
Hyphenate compound adjectives, such as “left-hand side”
Prefer “cannot” over “can not”