Rules for working on the user guide
To achieve a consistent result, all authors should remember a few rules.
Style
New pages should fit to the already existing ones. The reader should be addressed directly. She is assumed to be someone coming from another operating system, so she already has some experience working with a computer. Let's try to be reasonably serious, without getting dry and boring.
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> <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>
