Documentation
Style Guide
MOR-PLN-087 Version 1 Last Review Date: August, 2024

style guide

Much of what makes Markdown refreshing is the ability to write plain text and get great formatted output as a result. To keep the slate clean for the next author, your Markdown should be simple and consistent with the whole Site wherever possible.

Three simple guides:

  1. Source text is readable and portable.
  2. The Markdown site is maintainable over time and across teams.
  3. The syntax is simple and easy to remember.

Minimum viable documentation

A small set of fresh and accurate docs is better than a sprawling, loose assembly of “documentation” in various states of disrepair.

The Markdown way encourages us all to take ownership of documentation and keep them up to date.

Identify what you really need: release docs, API docs, testing guidelines.

Better is better than best The standards for an internal documentation review are different from the standards for code reviews. Reviewers should ask for improvements, but in general, the author should always be able to invoke the “Better/Best Rule.”

Fast iteration is your friend. To get long-term improvement, authors must stay productive when making short-term improvements.

As a reviewer of a documentation:

Prefer to suggest an alternative rather than leaving a vague comment. For substantial changes, start your own follow-up change log instead. Especially try to avoid comments of the form “You should also…”. On rare occasions, hold up submission if the change log actually makes the documentation worse. It’s okay to ask the author to revert.

As an author:

Avoid wasting cycles with trivial argument. Capitulate early and move on. Cite the Better/Best Rule as often as needed.

Markdown style guide

Markdown is a simple platform for internal and external documentation.

markdown bad style guide example

markdown is a dead-simple platform for internal and external documentation.

Document layout

In general, documents benefit from some variation of the following layout:

Document Title

Short introduction.

Topic

Content.

Document title: The first heading should be a level-one heading. The first level-one heading is used as the page

The very first line should have the document details,

ie.

MOR-PLN-087 Version 1 Last Review Date: August, 2024

Topic: The rest of your headings should start from level 2.

Headings

ATX-style headings

# Heading 1

## Heading 2

Use unique, complete names for headings

Use unique and fully descriptive names for each heading, even for sub-sections. Since link anchors are constructed from headings, this helps ensure that the automatically-constructed anchor links are intuitive and clear.

For example, instead of:

## Foo
### Summary
### Example
## Bar
### Summary
### Example

prefer:

## Foo
### Foo summary
### Foo example
## Bar
### Bar summary
### Bar example

Lists

Use lazy numbering for long lists

Markdown is smart enough to let the resulting HTML render your numbered lists correctly. For longer lists that may change, especially long nested lists, use “lazy” numbering:

1.  Foo.
1.  Bar.
    1.  Foofoo.
    1.  Barbar.
1.  Baz.

However, if the list is small and you don’t anticipate changing it, prefer fully numbered lists, because it’s nicer to read in source:

1.  Foo.
2.  Bar.
3.  Baz.

Code

Inline Backticks designate inline code that will be rendered literally. Use them for short code quotations, field names, and more:

You'll want to run really_cool_script.sh arg.

Pay attention to the foo_bar_whammy field in that table. Use inline code when referring to file types in a generic sense, rather than a specific existing file:

For code quotations longer than a single line, use a fenced code block:

def Foo(self, bar):
  self.bar = bar

Declare the language

It is best practice to explicitly declare the language, so that neither the syntax highlighter nor the next editor must guess.

Use fenced code blocks instead of indented code blocks Four-space indenting is also interpreted as a code block. However, we strongly recommend fencing for all code blocks.

add `copy to allow the code to be copied.

Indented code blocks can sometimes look cleaner in the source, but they have several drawbacks:

Escape newlines

Because most command-line snippets are intended to be copied and pasted directly into a terminal, it’s best practice to escape any newlines. Use a single backslash at the end of the line:

$ bazel run :target -- --flag --foo=longlonglonglonglongvalue \
  --bar=anotherlonglonglonglonglonglonglonglonglonglongvalue

Nest codeblocks within lists

If you need a code block within a list, make sure to indent it so as to not break the list:

  • Bullet.

    int foo;

  • Next bullet.

You can also create a nested code block with 4 spaces. Simply indent 4 additional spaces from the list indentation:

  • Bullet.

    int foo;

  • Next bullet.

Links

Long links make source Markdown difficult to read and break the 80 character wrapping. Wherever possible, shorten your links.

Use explicit paths for links within Markdown Use the explicit path for Markdown links. For example:

... You don’t need to use the entire qualified URL:

... (opens in a new tab) Avoid relative paths unless within the same directory Relative paths are fairly safe within the same directory. For example:

... ... Avoid relative links if you need to specify other directories with ../:

...

Use informative Markdown link titles

Markdown link syntax allows you to set a link title. Use it wisely. Users often do not read documents; they scan them.

Links catch the eye. But titling your links “here,” “link,” or simply duplicating the target URL tells the hasty reader precisely nothing and is a waste of space:

DO NOT DO THIS.

See the Markdown guide for more info: link, or check out the style guide here.

Check out a typical test result:

https://example.com/foo/bar (opens in a new tab).

Instead, write the sentence naturally, then go back and wrap the most appropriate phrase with the link:

See the Markdown guide for more info, or check out the style guide.

Check out a typical test result (opens in a new tab).

Images

Use images sparingly, and prefer simple screenshots. This guide is designed around the idea that plain text gets users down to the business of communication faster with less reader distraction and author procrastination. However, it’s sometimes very helpful to show what you mean.

Use images when it’s easier to show a reader something than to describe it. For example, explaining how to navigate a UI is often easier with an image than text. Make sure to provide appropriate text to describe your image. Readers who are not sighted cannot see your image and still need to understand the content! See the alt text best practices below.

import ModalImage from "react-modal-image";
import  menus from "../public/images/menus.png";
<ModalImage
  small={menus.src}
  large={menus.src}
  alt="CBC Menu Sample"
/>

Tables

Use tables when they make sense: for the presentation of tabular data that needs to be scanned quickly.

Avoid using tables when your data could easily be presented in a list. Lists are much easier to write and read in Markdown.

The list form is more spacious, and arguably therefore much easier for the reader to find what interests her in this case.

However, there are times a table is the best choice. When you have:

Relatively uniform data distribution across two dimensions. Many parallel items with distinct attributes. In those cases, a table format is just the thing. In fact, a compact table can improve readability:

Transport        | Favored by     | Advantages
---------------- | -------------- | -----------------------------------------------
Swallow          | Coconuts       | [Fast when unladen][airspeed]
Bicycle          | Miss Gulch     | [Weatherproof][tornado_proofing]
X-34 landspeeder | Whiny farmboys | [Cheap][tosche_station] since the X-38 came out

[airspeed]: http://google3/airspeed.h
[tornado_proofing]: http://google3/kansas/
[tosche_station]: http://google3/power_converter.h

Strongly prefer Markdown to HTML

Please prefer standard Markdown syntax wherever possible and avoid HTML hacks. If you can’t seem to accomplish what you want, reconsider whether you really need it. Except for big tables, Markdown meets almost all needs already.

Every bit of HTML hacking reduces the readability and portability of our Markdown corpus. This in turn limits the usefulness of integrations with other tools, which may either present the source as plain text or render it.

OverviewMarkdown Guide