SOIL Style Guide

The SOIL Style Guide contains guidelines for creating modern learning content to be received in an informal, conversational way.

💬 "How would I explain this in person?"

Some clarifications commonly found in more traditional written style guides are also included with considerations for modern digital media. For example,

  • How should I capitalize things?
  • Should I put punctuation inside quotation marks?
  • When should I end list lines with commas?
  • When do I use full sentences?
  • Should I use passive, active, or imperative voice?
  • When should I use code, italic, bold or bold italic?


While the organization of SOIL content is completely up to the creator there are some common components most share, such as

  • a landing used in marketing materials for linking,
  • an about with content about the content,
  • an index containing organized links into the content,
  • one to three divisions of main content,
  • a place with help and faq information,
  • a change log, and
  • a list of traditional references.

You can often combine these for small modules.


The landing is the first thing most people will see. It's like a book cover, front and back. It is seen by search engines and linked from marketing materials.


The main content is always included in any navigation menu and named something specific for the type of content. Some common names are

  • Learn
  • Create
  • Standard
  • Basics

The main content is often divided into two or more navigational menu items but rarely more than three. If more than three are needed consider subdividing the main content further.


  • contains frequently answered questions,





  • no spaces surrounding a dash,



Lists are always one level and always with either a star (*) or one (1.)


Use of contractions like don't and cannot are encouraged because they are a part of natural speech, the primary consideration when determining tone.

Always use single quote characters for contractions (') which can be rendered otherwise depending on the audience.

Visual Considerations

Here's a comparison of the default VuePress theme and that recommended for SOIL module content.

Black on White

Stick with simple black on white color themes which best support high contrast browser themes and extensions like Hacker Vision to universally apply dark mode.

💬 In the age of multiple monitors dark mode is becoming a requirement to avoid screen blindness from the intensity. Still this should be a user choice and not forced by the content creator.

Avoid Semi-transparent Colors

It has become popular to add a portion of transparency to font colors in an attempt to soften the font with subtle blurring. This makes the content incompatible with high contrast browser themes and dark mode inversion plugins and should therefore be avoided.

Avoid Dropshadow

As with semi-transparency, avoid the temptation to add drop shadow effects to images and other containers. These do not invert well when users apply dark mode filters and high contrast themes.

⚠️ Be particularly aware that the Apple Mac window screenshot automatically adds this to the image itself.

Not Academic

SOIL modules are not academic. They're educational. As such most of the traditional academic style guidelines won't apply to creating SOIL content.

Not for Print

SOIL modules are—by definition—not for print media.

However, if you follow the SOIL standard your content will automatically be print friendly. This is why the standard requires all content covered in interactive elements, images, video, and sound to be secondary to that covered in writing.

💬 Instead of thinking how your content will print you should be thinking of how it will sound when spoken. A comma might be preferred in one writing style and not in SOIL style because it creates unnatural pauses with voice synthesis.

Last Updated: 10/22/2018, 12:23:13 AM