Rules for working on the user guide
To achieve a consistent result, all authors should remember a few rules.
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.
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:
|<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|
|<pre class="terminal"><div>||For Terminal in/output. Example|
|For keyboard shortcuts. Use uppercase. Keys are separated with non-breaking spaces.|
|For command line applications.|
|For menu items. Separate menu, submenu, item with a " | ".|
- 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 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.
<tr><td class="onelinetop">Longest menu item
</td> <td width="15"> </td><td>Explanatory text