Documentation/Maemo Documentation Guidelines/General writing conventions

This section describes the general writing conventions for Maemo documentation. The writing conventions are based on Nokia Brand Book [1] and Nokia A-Z Marketing Language Guide [2].

Contents

[edit] Language to be used

Maemo documents are written in UK English.

If you need to check the spelling of some specific words, use Collins English Dictionary. For more information, use the Collins English Dictionary [3].

[edit] Headings

Maemo documents use the five heading styles and levels described in table 3.1.

Table 3.1: Heading styles and levels
Heading Style Level Numbering
\chapter{Chapter title} 0 (a)
\section{Section title} 1 (a.b)
\subsection{Subsection title} 2 (a.b.c)
\subsubsection{Subsubsection title} 3 (a.b.c.d)
\textbf{Paragraph title} 4 (a.b.c.d.e)

Each level 0 chapter (a) must start from a separate page.

Each level 1 section (a.b) must have a generic "a.1 Introduction" section (as the first section). In the introductive section, add links to example applications used and API docs referred to in the section.

Level 3 subsubsections (a.b.c.d) are the lowest level included in the table of contents.

If the purpose is NOT to have a section number and NOT to include section to the table of contents, add an asterisk (*) to the end of the header tag. For example, \subsection*{Example title} creates a level 2 heading without numbering and without adding it into the table of contents.

It is also possible to create level 4 paragraphs (a.b.c.d.e) but no lower than that. A level 4 paragraph has the following special features by default:

  • it is not included in the table of contents
  • it does not use section numbering
  • it cannot be referenced from the base text

For more information, see chapter #Creating cross-references and links.

[edit] Lists

List types can be divided into three categories:

Unordered lists
are also known as bullet lists. Use unordered lists when the specific order of the list items is not relevant.
Ordered lists
are also known as numbered lists. Use ordered lists when the order of the list items is relevant.
Step lists
are a subcategory of ordered lists, but used specifically for providing instructions on how to complete a procedure. Introduce each step list with an introductory sentence, using the syntax: To <do> <something>.

Keep lists simple. Do not include code examples or other complex items like tables or figures as a part of a list item. Avoid using nested list.

[edit] Tables

Keep tables as simple as possible. Use figures instead of complex tables.

Do not create complex structures, such as table cells including other elements than text. Avoid using multi-column cells for other purposes than creating subheadings for the table. If complex tables are needed create them outside LaTeX as images.

Basic instructions for table creation in LaTeX can be found from WikiBooks LaTex/Tables.

Each table must have a title that can be referenced.

[edit] Figures

When creating figures, it is recommended to use free graphics tools like InkScape or Gimp.

Provide figures in a high resolution format. If needed, high resolution figures are scaled down for HTML and PDF usage.

Image:Ambox_notice.png
 Screenshots can be low resolution if high resolution figures cannot be created.

For books and printing houses, resolution must be high enough. The recommendation is 300 dpi.

Use either PNG or JPEG format. PNG is recommended.

EPS format is not allowed in figures, because it cannot be used in PDF and HTML documents. For more information, see WikiBooks LaTex/Importing Graphics.

Basic instructions for figure creation in LaTeX can be found from WikiBooks LaTex/Floats, figures and Captions.

Each figure, including screen shots, must have a title that can be referenced.

[edit] Highlighting important text

Use Italics to highlight important words in base text, apart from command line examples and function or file names. Do not use Bold, or TextRaw for highlighting.

Do not use Italics for the following items:

  • sentences or chapters
  • product or component names (capitalize first letters instead of using formatting)
  • paragraph titles (use Bold instead)
  • example code and file names (use TextRaw instead)

Use Italics (at least) for the following items:

  • important words that need special attention from the reader
  • document names (with reference to Maemo Bibliography database)
  • For more information on highlighting a whole sentence or chapter, see chapters #Highlighting example code and #Creating notes

[edit] Highlighting example code

Use TextRaw or Verbatim to highlight command line examples and function or file names in base text. Do NOT use Italics for these. The difference between these two is that TextRaw allows normal LaTeX commands inside text will be ignored and handled as plain text.

Use TextRaw or Verbatim to highlight the following items:

  • paths and file names
  • source code examples
  • command line examples
  • screen output examples
  • environment variables
  • domain names and IP addresses

Use TextRaw for source code examples. Names need to be written exactly as in source code, for example, ThumbButton, SmallFont, PANGO_SCALE_SMALL, and ButtonTextColor.

Use TextRaw for command line examples and file names, for example, sources.list, /opt/bin/share, and apt-get install maemo-python-env.

Use references to the source code names in the following way:

  • For user to be able to cancel operation without saving modified data you need to add ThumbButton for your dialog.

For more information, see chapters #Highlighting important text, #Code listings, and #Command line and screen output examples.

[edit] Highlighting UI element names

Use Bold font to highlight user interface component caption names in text. For example, if you need to refer to a UI button with the caption Cancel use the caption Cancel as the element name and use Bold to highlight the name. Do NOT use Italics, TextRaw or Verbatim for highlighting UI element names.

Use TextRaw or Verbatim only for referring to source code name of the UI element.

Use references to the UI element names in the following way:

  • To cancel operation without saving modified data, press button Cancel in dialog.

For more information, see chapters #Highlighting important text, #Code listings, and #Command line and screen output examples.

[edit] Creating notes

Notes are used in documentation to make the reader pay attention to important issues that have to be taken into consideration. Do not add a note as a part of the body text. Instead, create each note on a separate row using NoteBox:

Image:Ambox_notice.png
 This is an example of a note.

Before using a NoteBox consider whether using Italics is enough to highlight the issue in the base text. Use NoteBox only for very important issues and avoid ending a section with it.

[edit] Creating cross-references and links

All Maemo documents must use the same LaTeX bibliography database. References added to the document from the bibliography database are added to the bibliography list automatically.

Use Maemo bibliography database references in the following way:

  • For more information on Nokia Brand, see document Nokia Brand Book [1].

To allow level 1 sections (a.b) to be reused in several different documents:

  • Do not link between level 1 sections (a.b) within a document. For example, do not make links from level 1 section (x.y) to subsections, tables, or figures located in another level 1 section (x.z).
  • Linking within level 1 section (x.y) is allowed.

Each level 1 section (a.b) must have a generic, introductive section (a.1 Introduction). The introductive section should contain:

  • A short introduction text about the purpose of the section.
  • Links to all example applications used in the section. The only allowed example links are to the Maemo examples project in Garage.
  • Links to all API docs referenced in the section. Links out of maemo.org are allowed for API docs.

If section Y referenced from the text is in the same level 1 section (a.b) as the text itself, create a section number link to section Y.

Use cross-references with section number link between sections in the following way:

  • For more information on topic X, see chapter #Creating cross-references and links.
  • For more information on topic X, see figure [/node3.html#fig:documentation_guidelines-introduction-n900 1.1].
  • For more information on topic X, see table 3.2.

If section Y referenced from the text is not in the same level 1 section (a.b) as the text itself, create a textual reference instead by using the chapter name in quotes. Do not use chapter numbers in textual references.

Use textual references between two level 1 sections (a.b) in the following way:

  • For more information on references, see chapter "How to write text references".
  • For more information on references, see figure "How to write text references".
  • For more information on references, see table "How to write text references".

Use Maemo bibliography database for references to other documents.

[edit] Trademarks

To check the correct spelling of common Nokia trademarks and product names, see chapter #Product names.

[edit] Acronyms

To check the correct spelling of common Nokia trademarks and product names, see chapter #Product names.

[edit] Clear and concise language

Use clear and concise language. Use the imperative in instructions, and avoid using the passive voice or empty expressions, if possible. See examples about how to use clear language expressions in table 3.2.

Table 3.2: Examples for clear language
Problem Incorrect Correct
There is/are as an empty expression. There is a possibility to do X. You can do X.
It is as an empty expression. It is possible to install X. You can install X.
Have/has as passive voice or an empty verb. X has the option of including Y. X can include Y.
Be/are/been as passive voice. This is done by installing X. For this, install X.
Using the future tense. A window will open. A window opens. Instead of the future tense (will), use the present tense.
Providing options to the reader. You can do this or that. Do this. To be as clear as possible and to avoid any ambiguity, do not give the user several options about what they can do. Be as direct as possible.
Redundant politeness. Please. Please is an empty expression that can usually be omitted.
Gender-specific language. He/she. Instead of the gender-specific terms he or she, use the more neutral they.
Conditional. Would. Using the conditional gives the impression of uncertainty. Avoid the conditional, and use the present tense instead. If this is not possible, use can.
Conditional. May/might. Using the conditional gives the impression of uncertainty. Avoid the conditional, and use the present tense instead. If this is not possible, use can.

[edit] Conjunctions

Use properly the conjunctions given in table 3.3.

Table 3.3: Proper usage of conjunctions
Incorrect Correct
since because
as because (except when used as synonymous to like)
when because (not instead of if)

[edit] Shortkeys

Use CTRL+C to refer to pressing the control and c keys together. Use the same TextRaw text formatting for all Shortkeys in base text as for command line examples inside text.

[edit] Abbreviations

To avoid sounding too casual, do not use apostrophes to mark possession or to form plural nouns. For more details, see table 3.4.

Table 3.4: Proper usage of abbvreviations
Incorrect Correct
*'ll instead of the future tense, use the present tense.
*'re write a two separate words, for example there are
*'s instead of device's platform, write device platform or use the preposition of to form the possessive: the platform of the device

[edit] Code listings

Separate source code example listings that are not part of the base text must fulfill the following requirements:

  • Code example needs to be inside a listing box that separates it from the base text.
  • Listing box should be connected to the surrounding base text with a reference.
  • Listing box must not have Caption or Label, e.g. listings cannot be refered from text.
  • Each piece of source code used in the example must be taken from an official example application in a Garage project. The validity of all such code examples must be tested.
  • All source code examples must use source code highlighting for better readability.
  • All source code examples must include comments explaining the functionality.
  • If the example code used is longer than 50 lines it is recommended (but not required) to include also copyright and licensing information in the beginning of the example code.
Image:Ambox_notice.png
 Each code example in a Garage project copyrighted by Nokia must use MIT-style licence to allow the free use of the example code.

Source code example types supported for listings are C/C++, CSS, HTML, Java, JavaScript, Latex, Pascal, Perl, PHP, Postscript, Python, Ruby, SQL, Tcl, Properties files, Makefile, XML, Log files, Ini files, Shell scripts and more.

The following is an example of how code listings can be connected to the surrounding text:

Example code below describes how to create... 

/*
* example_source.c, an example source code for kernel module
*
* Copyright (C) 2010 Nokia Corporation. All rights reserved.
*
* This maemo code example is licensed under a MIT-style license,
* that can be found in the file called "COPYING".
*
*/
 
#include <linux/module.h> /* needed by all kernel modules */
#include <linux/init.h>   /* needed for custom init/exit functions */
#include <linux/kernel.h> /* needed for KERN_ALERT macro */
 
/* Special macro to indicate license (to avoid tainting the kernel) */
MODULE_LICENSE("Dual MIT/GPL");
 
static int hello_init(void) {
printk(KERN_ALERT "Hello, world\n"); /* top priority message */
return 0;
}
 
static void hello_exit(void)
{
printk(KERN_INFO "Goodbye, world\n");
}
 
/* macros to mark modules init/exit funcs (run on insmod/rmmod) */
module_init(hello_init);
module_exit(hello_exit);

Example given above is the simplest way to implement...

Avoid ending a section with a listing box.

[edit] Command line and screen output examples

Separate command line and screen output examples that are not part of base text and are not source code examples must fulfill the following requirements:

  • Example needs to be inside a GrayBox that separates it from the base text.
  • Example box does NOT have a title and CANNOT be referenced.
  • Example does NOT get automatic source highlighting.
  • Example box should be connectied to the surrounding base text.

The following is an example of how a command line example within a GrayBox can be connected to the surrounding text (notice that an empty line must be given before GrayBox).

Following commands show how to... 

$ COMMAND LINE EXAMPLE IS HERE
$ ANOTHER COMMAND LINE IS HERE

Commands given above can be used also in...

Avoid ending a section with a GrayBox.

[edit] Product names

The following is an initial list of Maemo product names in alphabetic order:

  • Bora
  • Chinook
  • Debian
  • Diablo
  • Fremantle
  • Gregale
  • Harmattan
  • Maemo
  • maemo.org
  • Maemo C++
  • Maemo ESbox
  • Maemo Flasher-3.5
  • Maemo Host PC Connectivity
  • Maemo Mica Framework
  • Maemo PC Connectivity
  • Maemo PluThon
  • Maemo Python
  • Maemo Qt4
  • Maemo SDK
  • Maemo SDK Virtual Image
  • MaemoPad
  • Mistral
  • N800
  • N810
  • N810 WiMAX Edition
  • N900
  • Nokia 770
  • Scirocco
  • Scratchbox

The following table 3.5 presents the correct way to spell some product names:

Table 3.5: Proper usage of product names
Incorrect Correct
Maemo SDK(+) Maemo SDK
the Maemo SDK Maemo SDK
sbox Scratchbox
Maemo Virtual Image Maemo SDK Virtual Image
N810 Wimax N810 WiMAX Edition

[edit] References

  1. ↑ 1.0 1.1 Nokia Brand Book. http://brandbook.nokia.com
  2. ↑ Nokia A-Z Marketing Language Guide. http://brandbook.nokia.com
  3. ↑ Collins English Dictionary. http://www.collinslanguage.com
Retrieved from "http://wiki.maemo.org/Documentation/Maemo_Documentation_Guidelines/General_writing_conventions"