File:  [mozdev] / calendarhelp / www / write.html
Revision 1.14: download - view: text, annotated - select for diffs - revision graph
Sun May 1 09:17:34 2005 UTC (12 years, 5 months ago) by whiteley
Branches: MAIN
CVS tags: HEAD
mention draft.xbl (for testing context tags)

<!-- MAIN CONTENT -->
<h5 class="page-header">Guidelines for writers</h5>

<p>
This document contains guidelines for technical writers who write help
documentation for the project.
</p>

<blockquote>
<a href="#intro">Introduction</a><br>
<a href="#structure">The structure</a><br>
<a href="#source">The source files</a><br>
<a href="#symbols">Symbols</a><br>
<a href="#platform">Platform differences</a><br>
<a href="#version">Version differences</a><br>
<a href="#toc">The table of contents</a><br>
<a href="#index">The index</a><br>
<a href="#context">Contextual help</a><br>
<a href="#glossary">The glossary</a><br>
<a href="#style">Style and content</a><br>
<a href="#specials">Special paragraphs and subsections</a><br>
<a href="#images">Images</a><br>
<a href="#getting">Getting a source file to work on</a><br>
<a href="#test">Testing a source file</a><br>
</blockquote>

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


<h5 id="intro">Introduction</h5>
<p>
Sunbird's help system is based on the
<a href="http://www.mozilla.org/projects/help-viewer/index.php">Mozilla Help Viewer</a>,
but there are differences.
</p>

<p>
In addition, Sunbird help has some special features that impose restrictions on how you
write:
<ul>
<li>It is cross-platform.
Users on all operating system platforms get the
same help (though they see it in slightly different ways).</li>

<li>It is cross-version.
Users of all versions of Mozilla Calendar get the
same help, (though they see it in slightly different ways)</li>

<li>It is available in US English, and may also be available in other languages.</li>

<li>It is themed (skinned).
Users with different themes (skins) may see 
different layout and style.</li>

<li>It is available in an online viewer that works in a Mozilla web browser,
in addition to the standard help viewer</li>

</ul>
</p>

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


<h5 id="structure">The structure</h5>

<p>
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.)
</p>

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

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

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

<p>
The source files share a common stylesheet (<code>helpFileLayout.css</code>).
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.
</p>

<p>
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.
</p>



<h5 id="source">The source files</h5>

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

<p>
Each source file has exactly one <code>h1</code> 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
<code>&lt;h1 id="foo"&gt;</code> and this is the only <code>h1</code> tag.
</p>

<p>
The file's <code>title</code> tag and its <code>h1</code> tag have the same text content.

<p>
Every <code>h2</code> and <code>h3</code> 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.
</p>

<p>
You can use <code>h4</code>, <code>h5</code> and <code>h6</code> 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.
</p>



<h5 id="symbols">Symbols</h5>

<p>
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:
<blockquote>
<code>&amp;thiscal;</code> is either "Sunbird" or "Calendar"<br>
<code>&amp;thismozcal;</code> is either "Mozilla Sunbird" or "Mozilla Calendar"</br>
</blockquote>
</p>

<p><strong>Note:</strong>
An obsolete mechanism used <code>&lt;span&gt;</code> tags
with special style classes to achieve this.
</p>

<p>
When you are writing about differences between versions, you must use different
symbols that remain constant no matter which version the reader is using:
<blockquote>
<code>&amp;sunbird;</code> is the project name, "Sunbird", for now<br>
<code>&amp;mozcal;</code> is "Mozilla Calendar"<br>
</blockquote>
</p>

<p>
A symbol is defined for the Preferences window, named Options in Sunbird:
<blockquote>
<code>&amp;thispref;</code> is either "Preferences" or "Options"
</blockquote>
</p>



<h5 id="platform">Platform differences</h5>

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

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

<p>
You cannot use these classes on <code>h1</code>, <code>h2</code> or <code>h3</code> 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.)
</p>

<blockquote>
<pre>
win
mac
unix

noWin
noMac
noUnix
</pre>
</blockquote>
</p>

<p>
For example, if you use the tags:
<blockquote><pre>
&lt;span class="mac"&gt;Foo&lt;/span&gt;
&lt;span class="noMac"&gt;Bar&lt;/span&gt;
</pre></blockquote>
then Mac users see "Foo" but users on other platforms see "Bar".
</p>

<p>
Other classes are defined for some common platform-sensitive content.
Use these on <code>&lt;span&gt;</code> tags:

<table class="plain">
<thead>
<tr><td>Class</td><td>WIndows/Unix</td><td>Macintosh</td></tr>
</thead>
<tbody>
<tr><td><code>ctrlKey</code></td><td>Ctrl+</td><td>Cmd+</td></tr>
<tr><td><code>rightClick</code></td><td>right click</td><td>Ctrl-click</td></tr>
</tbody>
</table>

</p>


<h5 id="version">Version differences</h5>

<p>
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 <code>&lt;span&gt;</code>, <code>&lt;p&gt;</code>
and other paragraph-like tags.
You cannot use them on <code>h1</code>, <code>h2</code> or <code>h3</code> headings:
<blockquote><pre>
sunbird
extensions
</pre></blockquote>
</p>


<h5 id="toc">The table of contents</h5>

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



<h5 id="index">The index</h5>

<p>
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.
</p>

<p>
Specify each index entry in an <code>&lt;index&gt;</code> tag.
</p>

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

<p>
For example, this heading is indexed under B as "bar" and also under F as
"foo":
<blockquote><pre>
&lt;h2 id="alpha">Alphabets
   &lt;index&gt;foo&lt;/index&gt;
   &lt;index&gt;bar&lt;/index&gt;
&lt;/h2>
</pre></blockquote>
</p>

<p>
To specify a second-level entry, use a comma character.  For example:
<blockquote><pre>
   &lt;index&gt;word,order&lt;/index&gt;
   &lt;index&gt;order,of words&lt;/index&gt;
</pre></blockquote>
appears in the index under O as:
<blockquote><pre>
[-] O
      [-] order
            of words
</pre></blockquote>
and also under W as:
<blockquote><pre>
[-] W
      [-] word
            order
</pre></blockquote>
</p>


<h5 id="context">Contextual help</h5>

<p>
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.
</p>

<p>
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.
</p>

<p>
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 <code>chrome/calendar.jar</code>
</p>

<p>
You can only link to <code>h1</code>, <code>h2</code>, <code>h3</code> or <code>h4</code> tags
in the HTML.
</p>

<p>
Specify the links in a tag:
<blockquote><pre>
&lt;context window="window-id" element="element-id"/&gt;
</pre></blockquote>
</p>

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

<p>
For example, the product has a dialog window:
<blockquote><pre>
&lt;dialog id="calendar-new-eventwindow" ...
</pre></blockquote>
</p>

<p>
In the dialog there is a checkbox:
<blockquote><pre>
&lt;checkbox id="repeat-checkbox" ...
</pre></blockquote>
</p>

<p>
In the help, link from the checkbox element to the section heading:
<blockquote><pre>
&lt;h3 id="repeating"&gt;Repeating entries
   &lt;context window="calendar-new-eventwindow" element="repeat-checkbox" /&gt;
&lt;/h3&gt;
</pre></blockquote>
</p>


<h5 id="glossary">The glossary</h5>

<p>
If you are the writer responsible for the glossary, then you maintain the
source file glossary.xhtml.
</p>

<p>
Each <code>&lt;dt&gt;</code> tag in the glossary is automatically indexed.
If you need to add extra index entries, use the method described above.
</p>

<p>
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:
<blockquote><pre>
&lt;a href="glossary.xhtml#foo"&gt;foo&lt;/a&gt;
</pre></blockquote>
Don't forget the <code>x</code>!
</p>

<p>
You will need to look in glossary.xhtml to find the id.
</p>

<p>
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.
</p>

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



<h5 id="style">Style and content</h5>

<p>
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.)
</p>

<p>
Use US English spelling.
</p>

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

<p>
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.
</p>

<p>
For more information on style, see the
<a href="http://www.mozilla.org/projects/help-viewer/documentation_language-style.php">Help Viewer documentation</a>.
Some of the information there might not apply here, however.
</p>



<h5 id="specials">Special paragraphs and subsections</h5>

<p>
Four special paragraph classes are defined.
You can use them on a <code>&lt;p&gt;</code> tag or
on any other tag that behaves like a paragraph.
Use these tags to ensure consistent style throughout the help:
<blockquote>
<code>class="note"</code> for a note<br>
<code>class="idea"</code> for an idea or tip<br>
<code>class="see"</code> for a reference to further information<br>
<code>class="see-also"</code> for a reference to further information<br>
</blockquote>
</p>

<p>
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:
<blockquote><pre>
&lt;h4&gt;&lt;img class="mouse" src="chrome://calendarhelp/skin/mouse.png"/&gt; Using your mouse:&lt;/h4&gt;
&lt;p&gt;...&lt;/p&gt;

&lt;h4&gt;&lt;img class="keyboard" src="chrome://calendarhelp/skin/keyboard.png"/&gt; Using your keyboard:&lt;/h4&gt;
&lt;p&gt;...&lt;/p&gt;
</pre></blockquote>
</p>

<p>
For more information on tags, see the
<a href="http://www.mozilla.org/projects/help-viewer/documentation_coding-style.php">Help Viewer documentation</a>.
Some of the information there might not apply here, however.
</p>


<h5 id="images">Images</h5>

<p>
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.
</p>

<p>
If you must use an image, make a 256-color PNG file.
</p>

<p>
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.
</p>

<p>
Make the size of the image one of the standard sizes, and tag it using a
standard class in the <code>&lt;img&gt;</code> tag:
<blockquote>
<code>class="server-figure"</code> &nbsp;width 240 pixels, height 78 pixels<br>
<code>class="window-figure"</code> &nbsp;width 240 pixels, height 144 pixels<br>
</blockquote>
</p>

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


<h5 id="getting">Getting a source file to work on</h5>

<p>
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.
</p>

<p>
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.
</p>


<h5 id="test">Testing a source file</h5>
<p>
You can test a source file by viewing it in a Mozilla browser.
<p>

<p>
The style sheet <code>draft.css</code> together with the bindings <code>draft.xbl</code>
provide a special style that reveals
the <code>&lt;index&gt;</code> tags and entities.
You can modify <code>draft.css</code> if you prefer&mdash;it is not built
into the content pack.
</p>

<p>
To update the glossary, index, table of contents and context map you need this
project's <a href="build.html">builder</a> tool.
</p>

<hr>


FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>