Index ¦ Archives ¦ Atom ¦ RSS

Documentation Style Guide

I just wrote up a style guide for our team's documentation. The documentation is rendered using Gitbook and hosted on Github Pages. You can find the PR here but I figured it's worth sharing here as well.

Style Guide

Articles should be written in Markdown (not AsciiDoc). Markdown is usually powerful enough and is a more common technology than AsciiDoc.

Limit lines to 100 characters where possible. Try to split lines at the end of sentences. This makes it easier to reorganize your thoughts later.

This documentation is meant to be read digitally. Keep in mind that people read digital content much differently than other media. Specifically, readers are going to skim your writing, so make it easy to identify important information

Use visual markup like bold text, code blocks, and section headers. Avoid long paragraphs. Short paragraphs that describe one concept each makes finding important information easier.

Please squash your changes into meaningful commits and follow these commit message guidelines.

© Ryan T. Harter. Built using Pelican. Theme by Giulio Fidente on github.