Meter maintains a set of standard guidelines for our technical documentation. The objective is to maintain quality and consistency in delivering important and useful information for persons in need of technical guidance. These include, among other things, the style, tone, formatting procedures for the documentation as a whole, and the unique requirements of specific kinds of content.
Gitbook can accept many forms of documentation input, including markdown, Word, HTML, and more.
Each documentation file resides in the
source sub-directory, with the format
The naming convention for each of these files should correspond as closely to the title of the document as possible. It should be all lowercase (except in special circumstances), use hyphens for spaces, and include no special other characters. No greater than 24 characters should be used for the filename, not including the
.html.md file extension and hyphens.
The file structure should remain as flat as possible, with no more than one sub-directory representing an important high level topic or documentation section. Examples of this include
contributing. The top level
source directory, and all sub-directories underneath it, should include an
index.html.md file that provides a general overview of that section.
It will often be useful for contributors to build the documentation locally, to see if their modifications have no errors, and conform to the standards. This is a relatively straightforward procedure by running the following command:
$ bundle exec middleman build --clean
Middleman will take the name conforming Markdown files located in the
source sub-directory, and then generate static documentation in the
build sub-directory. Those static HTML files can be opened in a browser without any need for a server.
There is nothing specifically unique about Gitbook's use of Markdown, other than to make note about the ordering of code blocks and sections. The Outline of a Page section that follows should contain sufficient examples for how to use Markdown for Meter docs. If additional guidance is required, check out Gitbook's markdown documentation.
Every page will include the following:
A meta-data section at the very top of the source document.
A page title.
A body section.
Code blocks and command line examples (where relevant)
The meta-data section includes details such as title, language tabs (e.g. for code samples), links to other documents, and whether to include search on the page or not.
This section is written in Yaml as follows:
See Page Title
While just about any HTML can be used in the
toc_footers meta data, for Meter this should only ever include relative links, external links, links to anchors within a page, text for section titles, and section dividers (hr tags). The table of contents can be adjusted for each page individually, but should follow some convention.
The navigation should always include all top level topics within the documentation. Therefore, at the very least a link to that topic's main index page should be included within the
toc_footers. When the current document belongs to a particular topic (e.g.
API Documentation), the topic is considered to be the active one. That document and all other documents that belong to that topic should also be included in
toc_footers. Inactive topics might also include noteworthy links, as well as its index page.
toc_footers:- <a href='./index.html'>Documentation Home</a>- First Topic- <a href='./first-topic/index.html'>First Topic</a>- <a href='./first-topic/the-active-document.html'>The Active Document</a>- <a href='./first-topic/one-same-topic-doc.html'>One Same Topic Doc</a>- <a href='./first-topic/another-same-topic-doc.html'>Another Same Topic Doc</a>- <hr>- Second Topic- <a href='./second-topic/index.html'>Second Topic</a>- <a href='./second-topic/a-noteworthy-doc.html'>A Noteworthy Doc</a>- <hr>- Third Topic- <a href='./third-topic/index.html'>Third Topic</a>- <a href='./third-topic/a-noteworthy-doc.html'>A Noteworthy Doc</a>- <hr>- <a href='https://www.meter.io/external-link/'>An Important External Link</a>- <a href='https://www.meter.io'>Meter.io</a>
In general the language tab meta-data must be in one of the languages listed here: https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers.
However, depending on the document, for Meter this will generally always be either
bash (but never both). Most developer documents will use
bash. This use of a single tab does not affect the use of Markdown code blocks in any way, but makes it easier for the reader to not need to switch back and forth between tabs unnecessarily.
The search mechanism is limited to only searching within the current, but it is advisable to always set this to true, for convenience.
Readers should have a good sense what the document is about in a reasonable amount of words. Make all document titles as intuitive as possible, and avoid making them too long or too short. Less than 30 characters long, and preferably no more than 24, is ideal. One of the purposes for this is that titles that are too long may get cut off in the side navigation.
Write a brief intro on the main topic, in two or three sentences. In one paragraph, give the reader a short and direct summary of what to expect in the document. Convince them to continue reading.
The body section of the document will contain all the topic sub-headings. It does not require a title or any summary overview of its own. However, if there are four or more sub-headings a table of contents before any sub-headings may be useful to help navigate the page. Even child topics within sub-headings may be desirable in some situations.