markdown-style.md

Mesos Markdown Style guide

Documentation is an integral part of every good feature as it describes the intended usage and enable new users to start using and understanding the feature. User guides and non-code technical documentation is stored in markdown files in the docs/ folder. These files get rendered for the online documentation. This guide introduces a consistent documentation style to be used across the entire non-code documentation.

Note: As of right now this is work in progress and the existing documentation might not yet comply to this style.

What to document?

Any new feature should be documented in its own markdown file. If the link between source code and documentation is not obvious, consider putting a short comment into the code stating that changes at this part of the code should be reflected as well in the documentation.

Keep documentation and style-guides in Sync with code?

When changing code consider whether you need to update the documentation. This is especially relevant when introducing new or updating command line flags. These should be reflected in configuration.md!

Code Examples

Code examples should be specified as follows:

    ~~~{.cpp}
    int main(int argc, char** argv)
    {
      ....
    }
    ~~~

Notes/Emphasis

Notes are used to highlight important parts of the text and should be specified as follows.

**Note:**  Short note.
Continued longer note.

In order to highlight individual words in a sentence such as certain identifiers:

Use the default `HierarchicalDRF` allocator....

Commands

Example commands should be specified as follows:

`mesos-master --help`

Files/Path

Files and path references should be specified as follows:

Remember you can also use the `file:///path/to/file` or `/path/to/file`

Tables

In order to avoid problems with markdown formatting we should specify tables in html directly:

<table class="table table-striped">
  <thead>
    <tr>
      <th width="30%">
        Flag
      </th>
      <th>
        Explanation
      </th>
  </thead>

  <tr>
    <td>
      --ip=VALUE
    </td>
    <td>
      IP address to listen on

    </td>
  </tr>
  <tr>
    <td>
      --[no-]help
    </td>
    <td>
      Prints this help message (default: false)

    </td>
  </tr>
</table>

Indendation and Whitespace

We use no extra indentation in markdown files. We have one new line after section headings and two blank lines in between sections.

... end of previous section.


## New Section

Beginning of new section ....