The Real&Mate formatting options are a mix of HTML and custom reusable web elements. Below are listed all these content formatting options as well as guidelines and best practices to follow when writing for Real&Mate's Documentation.

Table of Contents

Content Formatting

Titles

Titles are the base of a documentation structure, as they shape the content by separating it into coherent sections.

There is only one H1 title, at the beginning of the documentation file. Other titles can be used several times throughout the file and must keep a logical order.

  • Titles must be short, and at the same time give a clear idea of what topic will be tackled in the related documentation section.
  • Titles shouldn't be a question.
  • Titles should all have a similar format, especially titles of the same level.
  • Titles can emphasise the action that is tackled in the following documentation by starting with an action verb (e.g. "Writing content", "Creating content-types").
<h1>H1 title</h1> <h2>H2 title</h2> <h3>H3 title</h3> <h4>H4 title</h4> <h5>H5 title</h5>

Text Highlights

Text highlights are basic formatting that represent and/or highlight items from user interfaces:

  • italics: for GUI section, window and field names.
  • bold: for button names.
  • code: for small code excerpts, file names and paths.
<i>italics</i> <b>bold</b> <code>code</code>

Notes

Notes highlight information by separating it from the regular, main content.

New entries are only considered created once some of their content has been written and saved. Only then will the new entry be listed in the list view.

<note><p> New entries are only considered created once some of their content has been written and saved. Only then will the new entry be listed in the list view. </p></note>

Lists

Lists allow to group sets of related items:

  • Bullet lists are for same-level items. They are used where enumeration isn't necessary.
  • Numbered lists are for procedures. Each number describes an action that will lead a user to complete a goal.

Always start with a capital letter and finish with a period.

Bullet List

The name of the subscription plan:<ul> <li><code>Starter</code>.</li> <li><code>Standard</code>.</li> <li><code>Premium</code>.</li> <li><code>Enterprise</code>.</li> </ul>

Numbered List (Procedure)

To start receiving webhook events in your app, create and register a webhook endpoint:<ol> <li>Create a webhook endpoint handler to receive event data POST requests.</li> <li>Test your webhook endpoint handler.</li> <li>Register your endpoint within Real&Mate.</li> <li>Secure your webhook endpoint.</li> </ol>

Code Examples

Code examples are displayed in a console-like style, that also contains a "Copy" button for easier use.

<codeblock>Necessary code goes here.</codeblock>

Details

Details are elements that by default only display a title, as the rest of the content is collapsed. It's used for content that can be hidden by default to make documentation shorter and cleaner.

Title of the Details Necessary content goes here.
<details> <summary> Title of the Details </summary> Necessary content goes here. </details>

Tables

Tables display more clearly complex groups of items related to the same kind of information.

Title 1 Title 2 Title 3 Title 4 Title 5 Title 6 Title 7
Key Item Item Item Item Item Item Item
Key Item Item Item Item Item Item Item
<table> <thead> <tr> <th>Title 1</th> <th>Title 2</th> <th>Title 3</th> <th>Title 4</th> <th>Title 5</th> <th>Title 6</th> <th>Title 7</th> </tr> </thead> <tbody> <tr> <td>Key Item</td> <td>Item</td> <td>Item</td> <td>Item</td> <td>Item</td> <td>Item</td> <td>Item</td> </tr> <tr> <td>Key Item</td> <td>Item</td> <td>Item</td> <td>Item</td> <td>Item</td> <td>Item</td> <td>Item</td> </tr> </tbody> </table>

Illustrations

Screenshots

Screenshots show contents of a device display.

  • Prefer screenshots of the whole interface instead of cutting only part of it. It's easier for a user to locate where something is on the interface using a context.
  • To indicate a specific area of the screenshot that's mentioned in the documentation, edit the screenshot to add a rectangular shape around the area. The shape should blue (#37aef7), and its lines should be 3px wide.
 Style Guide <img alt="Style Guide" title="Style Guide" src="assets/screenshots/style-guide.jpg" class="screenshot" />

Buttons

Buttons are used to replicate those used on Real&Mate user interfaces (for example, the admin panel), to help users locate them on the interface. Buttons are available in the assets/buttons folder, in the SVG format, and should be integrated in the documentation files as images.

Click Arrow counterclockwise to refresh the window.

Click <img alt="Arrow counterclockwise" src="assets/buttons/arrow-counterclockwise.svg" /> to refresh the window.
Verified by World Wide Web Consortium:  W3C