mozdev.org

CalendarHelp

resources:
developer:
project:
projects:

This document contains guidelines for technical writers who write help documentation for the project.

Introduction
The structure
The source files
Symbols
Platform differences
Version differences
The table of contents
The index
Contextual help
The glossary
Style and content
Special paragraphs and subsections
Images
Getting a source file to work on
Testing a source file

Note: When you see the term "Sunbird" in this document, it refers to any version of Mozilla Calendar.

Introduction

Sunbird's help system is based on the Mozilla Help Viewer, but there are differences.

In addition, Sunbird help has some special features that impose restrictions on how you write:

When a user opens the Help, the user sees only the appropriate help for their current platform, version, language and theme.

The structure

Sunbird's help is multilingual. There is a separate version of the content for each locale. (The help viewer engines and the style information are shared between locales.)

The help is written for the locale en-US and translated into other languages.

The content of Sunbird's help is stored in more than a dozen separate source files.

The source files are all stored in the same directory, so they have unique names.

The source files share a common stylesheet (helpFileLayout.css). This stylesheet is part of the skin. Different themes can change it. Do not include style information in a source file. Try to avoid using special styles. If you have a good reason to use a special style, ask to have it included in the shared stylesheet.

The table of contents (ToC), the index and a context map are built from information in the source files. The glossary index is built from the glossary source file.

The source files

Each source file is an xhtml file in the directory text/en-US. It contains HTML in an XML wrapper. This means that the HTML tagging must be exact. For example, you cannot omit </p> at the end of a paragraph—the XML parser requires end tags. For another example, you cannot write <br>—you must write <br/> instead.

Each source file has exactly one h1 tag. This tag has an id that is the same as the name of the source file. For example, in the file foo.xhtml, there is a tag <h1 id="foo"> and this is the only h1 tag.

The file's title tag and its h1 tag have the same text content.

Every h2 and h3 tag has an id. In the normal way, each id is unique within the source file. It is OK for different source files to use the same ids for these and other tags.

You can use h4, h5 and h6 if you need to. These tags do not need to have ids at present, but it is a good idea to give them ids in case the requirement changes in the furture.

Symbols

Symbols are defined for the product name. You must use these symbols when you want the name to reflect the product that the reader is using:

&thiscal; is either "Sunbird" or "Calendar"
&thismozcal; is either "Mozilla Sunbird" or "Mozilla Calendar"

Note: An obsolete mechanism used <span> tags with special style classes to achieve this.

When you are writing about differences between versions, you must use different symbols that remain constant no matter which version the reader is using:

&sunbird; is the project name, "Sunbird", for now
&mozcal; is "Mozilla Calendar"

A symbol is defined for the Preferences window, named Options in Sunbird:

&thispref; is either "Preferences" or "Options"

Platform differences

Style classes are defined for operating system platform groups, when you want to hide content that is not appropriate for the reader's platform.

You can use these style classes on <span>, <p> and other paragraph-like tags. You must specify only one class in each tag.

You cannot use these classes on h1, h2 or h3 headings, because the table of contents does not support them. (This restriction is likely to be lifted in a future version of the help viewer.)

win
mac
unix

noWin
noMac
noUnix

For example, if you use the tags:

<span class="mac">Foo</span>
<span class="noMac">Bar</span>
then Mac users see "Foo" but users on other platforms see "Bar".

Other classes are defined for some common platform-sensitive content. Use these on <span> tags:

ClassWIndows/UnixMacintosh
ctrlKeyCtrl+Cmd+
rightClickright clickCtrl-click

Version differences

Style classes are defined for Sunbird and extensions, when you want to hide content that is not appropriate for the version the reader is using. You can use these styles on <span>, <p> and other paragraph-like tags. You cannot use them on h1, h2 or h3 headings:

sunbird
extensions

The table of contents

The ToC generator uses the h1, h2 and h3 tags to build the ToC. It ignores lower-level headings.

The index

You can add index entries to any tag that has an id, but it is usual to add them only to headings. This ensures that a reader arriving from the index starts reading in a sensible place.

Specify each index entry in an <index> tag.

The index tag must be inside a tag that has an id, and it must follow the text content of the tag (if there is any).

For example, this heading is indexed under B as "bar" and also under F as "foo":

<h2 id="alpha">Alphabets
   <index>foo</index>
   <index>bar</index>
</h2>

To specify a second-level entry, use a comma character. For example:

   <index>word,order</index>
   <index>order,of words</index>
appears in the index under O as:
[-] O
      [-] order
            of words
and also under W as:
[-] W
      [-] word
            order

Contextual help

When the user press the Help key, or a Help button in a dialog, the help opens to the topic that describes the element in the user interface that has focus. To make this happen, you create links from the product user interface to the help.

You can link from any focusable element in the interface, or from any parent of a focusable element, at any level in the hierarchy up to the window or dialog.

The element that you link from must have an id in the XUL source file. To identify the id, either look at the appropriate XUL source file or use the DOM Inspector tool to inspect the window containing the element. You can get the XUL source files from CVS or by using a zip or jar tool to unpack a copy of your installed chrome/calendar.jar

You can only link to h1, h2, h3 or h4 tags in the HTML.

Specify the links in a tag:

<context window="window-id" element="element-id"/>

The context tag must be inside an h1, h2 or h3 tag that has an id, and it must follow the text content of the tag.

For example, the product has a dialog window:

<dialog id="calendar-new-eventwindow" ...

In the dialog there is a checkbox:

<checkbox id="repeat-checkbox" ...

In the help, link from the checkbox element to the section heading:

<h3 id="repeating">Repeating entries
   <context window="calendar-new-eventwindow" element="repeat-checkbox" />
</h3>

The glossary

If you are the writer responsible for the glossary, then you maintain the source file glossary.xhtml.

Each <dt> tag in the glossary is automatically indexed. If you need to add extra index entries, use the method described above.

If you are writing some other source file, link to the glossary the first time you use a glossary term in a section. A glossary link looks like:

<a href="glossary.xhtml#foo">foo</a>
Don't forget the x!

You will need to look in glossary.xhtml to find the id.

Do not link the term again in the same section. If you start a new section (with a heading tag), and you use the term again, link to the glossary again. This is because a reader can jump into any section from the ToC or the index.

If you need a new term in the glossary, send the term, id and definition to the writer responsible for glossary.xhtml.

Style and content

Use simple direct language, so that the help is easy to use by people whose first language is not English, and easy to translate. (For example, the previous sentence is too long and complex. Three separate sentences would be better.)

Use US English spelling.

Use US English syntax, but if you have a choice of syntax, choose with regard for international readers.

Make each section self-contained and make its relationship to other sections clear. This is beacause you do not know where a reader will start reading.

For more information on style, see the Help Viewer documentation. Some of the information there might not apply here, however.

Special paragraphs and subsections

Four special paragraph classes are defined. You can use them on a <p> tag or on any other tag that behaves like a paragraph. Use these tags to ensure consistent style throughout the help:

class="note" for a note
class="idea" for an idea or tip
class="see" for a reference to further information
class="see-also" for a reference to further information

Use separate subsections for users who prefer to use a mouse, and for users who prefer to use the keyboard. These subsections have images to identify them in a consistent way throughout the help. For example:

<h4><img class="mouse" src="chrome://calendarhelp/skin/mouse.png"/> Using your mouse:</h4>
<p>...</p>

<h4><img class="keyboard" src="chrome://calendarhelp/skin/keyboard.png"/> Using your keyboard:</h4>
<p>...</p>

For more information on tags, see the Help Viewer documentation. Some of the information there might not apply here, however.

Images

Avoid product images and screenshots unless there is good reason for them. Normally, anyone who reads the help already has the product running. A screenshot is rarely much use, especially as it may be of a different version on a different operating system platform with a different theme.

If you must use an image, make a 256-color PNG file.

If there is text in the image, make a separate version of the image with no text so that translators can add text in other languages.

Make the size of the image one of the standard sizes, and tag it using a standard class in the <img> tag:

class="server-figure"  width 240 pixels, height 78 pixels
class="window-figure"  width 240 pixels, height 144 pixels

If you need a different size, ask to have it added to the shared style.

Getting a source file to work on

Before you start working on a source file, make sure that the piece of work you plan to do is recorded in Bugzilla. You can get the source file from CVS, or you can ask the project owner to send it to you.

When you have completed a draft, attach the file to the bug report. Your changes will be reviewed and edited before the file is updated in the project.

Testing a source file

You can test a source file by viewing it in a Mozilla browser.

The style sheet draft.css together with the bindings draft.xbl provide a special style that reveals the <index> tags and entities. You can modify draft.css if you prefer—it is not built into the content pack.

To update the glossary, index, table of contents and context map you need this project's builder tool.


The calendarhelp project can be contacted through the mailing list or the member list.
Copyright © 2000-2017. All rights reserved. Terms of Use & Privacy Policy.