Tiny Content Style Guide

This tiny content style guide will help you get consistent with your writing. I took the inspiration to write this guide from so many other famous content style guides like Microsoft Style Guide, MailChimp Style Guide and so on.

If you’re new to content styling, use the following rules to get started and tweak it to suit your needs.

Tone

For technical content, you should focus on helping your readers learn and understand. Following guidelines will help you achieve that:

• Active voice: Active voice makes content more engaging and direct.
• Brevity: Most readers are scanning the content. Writing less will make content easier to scan. However, don’t sacrifice clarity.
• Instruct: Instruct the readers when required. It feels awkward initially for you as a writer; however, it’ll help the readers get things done.
• Write for humans: Your readers are human beings. Address them directly, and use a friendly, conversational tone. Using you to address them will make content immediately friendly.

Code examples

Following are some guidelines for writing code examples.

Highlight the code

Highlight the relevant part of the code snippet. For example, if you’re writing a blog on filter method of JavaScript arrays, you’d highlight like following:

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
// highlight-start
const oddNumbers = numbers.filter((num) => num % 2 !== 0);
// highlight-end

Avoid console.log or print

Avoid console.log, print, or similar functionality in your code examples. If you need them to explain something, write the output in comments as follows:

const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const oddNumbers = numbers.filter((num) => num % 2 !== 0);

// highlight-start
console.log(oddNumbers); // 1, 3, 5, 7, 9
// highlight-end

Use placeholders

Use placeholders if you want the reader to replace values in code examples with the reader’s personalized values. For example, if you’re calling an API that needs an API key, use a placeholder for the API key and explain the placeholder as follows:

// highlight-start
const API_URL = "https://example.com/example-api?api-key=<API-KEY>";
// highlight-end
const weatherData = fetch(API_URL).then((response) => response.json());

Indicate omitted code with ellipses

If you’re omitting some code in your code examples, indicate that using ellipses or three consecutive dots in a comment as follows:

import { StreamState } from "../interfaces/stream-state";

export class AudioService {
  // ...
  private state: StreamState = {
    playing: false,
    readableCurrentTime: "",
    readableDuration: "",
    duration: undefined,
    currentTime: undefined,
    canplay: false,
    error: false,
  };
}

Test your code

Always test your code examples by compiling and running them. The last thing you want is to lose the trust of your reader.

Punctuation

• Use straight quotes instead of curly(smart) quotes.
• Use serial commas (also known as Oxford commas) when writing a list.
• Avoid exclamation marks.
• Avoid ampersands unless they’re part of a brand or company name.

Alternative words