| Version 4 (modified by , 15 years ago) ( diff ) |
|---|
Rules for working on the user guide
To achieve a consistent result, all authors should remember 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> <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>
Note:
See TracWiki
for help on using the wiki.
