Home · All Classes · Grouped Classes · Annotated · Functions

Qtopia Style Guide: Online Help

Purpose

The purpose of this document is to set out what information the online help for Qtopia should contain and how that information is to be formatted. This includes the positioning of tags, use of headings and images, and the rules governing when such hyperlinks as See Also should be used.

Content

Qtopia's help pages are written in a subset of the HTML language.

The Qtopia online help system provides the capability to provide context-sensitive help for any screen displayed by the Qtopia server or by a Qtopia application. The QObject::setObjectName() function should be called when constructing each screen in order to set the name that the Help Browser will use to find the correct help page.

Each help page should describe the purpose of the corresponding screen and what actions the user can perform on that screen, including the meaning of each menu option. Due to the restricted screen space on most devices, help descriptions should be brief and concise. The main help page for an application will generally also provide links to the pages describing the main screens provided by that application.

Help pages should be written to be applicable in all cases. If there is something dynamic that would change the documentation, there are a number of ways to use the Help Browser Preprocessor to present the correct content. The preprocessor can handle both device-specific content and content that depends on certain boolean properties of a running Qtopia system.

Headings

Each help page should include a title tag. This title will be displayed in Qtopia's title bar when the page is being viewed in the Help Browser. As the page title will therefore always be visible to the user, there is no need to include the title in the body of the page.

Long pages may contain sub-headings, though overly long pages should be divided into smaller pages referenced by hyperlinks from the main topic page.

Images and Icons

Images and icons may be used freely in help pages, but each page should generally reference only the following images and icons: <ul> <li>the set of images and icons that belong to that application (i.e. those installed by the application's project file at build time),</li> <li>the set of images and icons that are shared by all applications (i.e. those installed by the Qtopia server's project file at build time), and>/li> <li>the icons provided by the help browser itself (such as the icon for the directional keypad).</li> </ul>

Images and icons are referenced using the same naming scheme that is used in Qtopia source code. This naming scheme is aware of internationalization. For example:

    <img src=":icon/options"> </img> Options menu icon
    <img src=":icon/i18n/back"> </img> Back icon used in context bar.  Differs for left-to-right and right-to-left languages.
    <img src=":icon/help/dpad"> </img> Icon for the directional keypad.
    <img src=":image/qtopia"> </img> Qtopia logo.

When writing help text, it is important to remember that Qtopia's soft-menu bar can display either text labels or icons. Therefore, when referring to the soft-menu bar, help text should include both the text and the icon of the soft-menu item, as shown below.

    To abandon the message completely, press <img src=":icon/options"><b>Options</b> and select <b>Cancel</b>.

In some cases, a help author will want to place a space after an image in the help text. To make this work, you must include the whitespace within the image tag, as shown below.

    <img src=":icon/datebook/audible"> </img> shows that a task has an audible reminder.

Layout

This section explains when different terms, methods of sectioning, and images should be used.

TermUsage
IndexApplied to a topic page that lists subordinate pages
See AlsoUsed when a topic outside the current one is of direct relevance and does not have an in-text link (in-text links are preferred).
Fullstops in listsUse a fullstop if the list item is a complete sentence or a significant sentence fragment.
HyphenateAlways hyphenate the following: pop-up, check-box, combo-box,
Do not hyphenateDo not hyphenate the following: email
BoldUse bold tags for the following: menu options, screen names, key / button names, and fields,
Screen or DialogUse the term dialog when referring to a message directed at the user that requires a response (a dialog between device and user) all others are screens (even though they collect input in fields etc).
WindowDo not use this term. Instead use the term screen or dialog (see above for clarification).

Rules on Hyperlinks

ItemRule
See AlsoThis should only be used if the link cannot be placed neatly within the text.
Back/parent linksShould not be used since Qtopia's Help Browser has a Back function and since most pages can be reached in a variety of ways (resulting in an unclear return path).
Go toAvoid using this if possible. Used for main topic pages that can be reached via more than one parent. This does not include links from child pages belonging to another main topic.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3