wiki:i18n/en_EN/StyleGuide

Version 3 (modified by humdinger, 9 years ago) (diff)

--

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:

CodeComment
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>