Rules for working on the user guide

To achieve a consistent result, all authors have to respect a few rules.

Formatting

In general, it's a good idea to look into existing pages and maybe copy and paste sections whose formatting fits your purposes. There are a couple of CSS classes to get a consistent appearance:

Code	Comment
Text boxes
<div class="box-info"><div>	To make tips or infos more visible. Use sparingly. ​Example
<div class="box-stop"><div>	To point out some critical issue. ​Example
<div class="box-warning"><div>	To warn about serious consequences. ​Example
Terminal output
<pre class="terminal"><div>	For Terminal in/output. ​Example
In-text formatting
<span class="key"></span>	For keyboard shortcuts. Use uppercase. Keys are separated with non-breaking spaces.
Example: <span class="key">ALT</span>&nbsp;<span class="key">C</span>
<span class="cli"></span>	For command line applications.
Example: <span class="cli">catattr</span>
<span class="app"></span>	For applications.
Example: <span class="app">ActivityMonitor</span>
<span class="path"></span>	For paths.
Example: <span class="path">/boot/home/config/be</span>
<span class="menu"></span>	For menu items. Separate menu, submenu, item with a " | ".
Example: <span class="menu">Font | Size | Increase</span>
<span class="button"></span>	For buttons.
Example: <span class="button">Apply</span>

In General

Images

• Screenshots should be cropped to the window borders with a transparent background (think of the yellow window tab).
• No mouse pointer in the picture, unless it shows some action requiring the mouse.
• Images are normally PNG, their width and height tags are not used to make changing files possible without touching the text.

Tables

Tables should be used if you have a couple of e.g. buttons or menus that are to be explained with a short text (e.g. see ​at bottom of Twitcher. Between the object (button or menu) and the explanation should be a 15 pixel wide empty column. To avoid unwanted linebreaks and align text to the top, use the class "onelinetop" of a cell.
Example: <tr><td class="onelinetop">Longest menu item</td> <td width="15"> </td><td>Explanatory text</td></tr>