Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Eclipse Doc Style Guide"

m (added ids)
m (Change broken link to DITA)
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<p>This document gives the style conventions to be used in [[Eclipse Documentation | Eclipse help]]. The Eclipse help has the following topic types: Tutorial (Getting Started), Concept, Task, and Reference. These topic types are based on the [http://www-106.ibm.com/developerworks/xml/library/x-dita1/ Darwin Information Typing Architecture (DITA)] standards.
+
<p>This document gives the style conventions to be used in [[Eclipse Documentation | Eclipse help]]. The Eclipse help has the following topic types: Tutorial (Getting Started), Concept, Task, and Reference. These topic types are based on the [http://www.ibm.com/developerworks/library/x-dita1/ Darwin Information Typing Architecture (DITA)] standards.
  
 +
 +
===Topic Titles===
 
<table border="1" cellpadding="3" cellspacing="0">
 
<table border="1" cellpadding="3" cellspacing="0">
 
+
<tr id="titles"><th>Guideline</th><th>Example</th></tr>
<!-- *************************** topic titles ************************ -->
+
 
+
<tr id="titles"><th>Topic Titles</th><th>Example</th></tr>
+
  
 
<tr>
 
<tr>
Line 46: Line 45:
 
<td><b>Creating a project</b></td>
 
<td><b>Creating a project</b></td>
 
</tr>
 
</tr>
 +
</table>
  
<!-- *************************** lists ************************ -->
+
===Lists===
 
+
<table border="1" cellpadding="3" cellspacing="0">
<tr id="lists"><th>Lists</th><th>Example</th></tr>
+
<tr id="lists"><th>Guideline</th><th>Example</th></tr>
  
 
<tr>
 
<tr>
Line 95: Line 95:
 
</tr>
 
</tr>
  
<!-- *************************** inline markup ************************ -->
+
<tr>
 +
<td>When describing menu items, use third-person descriptive verb tenses rather than imperative ones.</td>
 +
<td><s>Create</s> a new file -> <b>Creates</b> a new file
 +
</tr>
 +
</table>
  
<tr class="break" id="inline-markup"><th>Inline Markup</th><th>Example</th></tr>
+
===Inline Markup===
 +
<table border="1" cellpadding="3" cellspacing="0">
 +
<tr class="break" id="inline-markup"><th>Guideline</th><th>Example</th></tr>
  
 
<tr>
 
<tr>
Line 138: Line 144:
 
</td>
 
</td>
 
</tr>
 
</tr>
 +
</table>
  
<!-- *************************** Topic content ************************ -->
+
===Topic Content===
 
+
<table border="1" cellpadding="3" cellspacing="0">
<tr id="content"><th>Topic Content</th><th>Example</th></tr>
+
<tr id="topic-content"><th>Guideline</th><th>Example</th></tr>
  
 
<tr>
 
<tr>
Line 171: Line 178:
  
 
<tr>
 
<tr>
<td>Document how to access a feature through the menu bar, as opposed to
+
<td>Document how to access a feature through the menu bar, as opposed to using toolbar buttons or the context menu.  
using toolbar buttons or the context menu.  
+
  
<p>Avoid providing multiple ways to do something unless the menu-driven method is  
+
<p>Avoid providing multiple ways to do something unless the menu-driven method is not always available. Project properties are an example of this: you can set project properties in the New Project wizard, but after the project is created you can set properties only by right-clicking on an individual project or in preferences (for all projects).</p>
not always available.  
+
Project properties are an example of this:  
+
you can set project properties in the New Project wizard, but after the project is  
+
created you can set properties only by right-clicking on an individual  
+
project or in preferences (for all projects).</p>
+
 
</td>
 
</td>
 
<td>Click <b>File &gt; New &gt; Project</b>.
 
<td>Click <b>File &gt; New &gt; Project</b>.
Line 188: Line 189:
  
 
<tr class="break">
 
<tr class="break">
<td>When you must provide multiple ways to do something use the  
+
<td>When you must provide multiple ways to do something use the format in the example.</td>
format in the example.</td>
+
 
<td>
 
<td>
 
<ol>
 
<ol>
Line 220: Line 220:
 
</td>
 
</td>
 
</tr>
 
</tr>
 
 
<tr>
 
<tr>
<td>When describing how to use the context menu (shortcut menu),  
+
<td>When describing how to use the context menu (shortcut menu), instruct the user to &quot;right-click &lt;something&gt; and select &lt;something&gt;.&quot;
instruct the user to &quot;right-click &lt;something&gt;  
+
<p>Do not say, &quot;From the context-menu, choose &lt;something&gt; as the term context-menu is not obvious to new users.</p>
and select &lt;something&gt;.&quot;
+
<p>Do not say, &quot;From the context-menu, choose &lt;something&gt;
+
as the term context-menu is not obvious to new users.</p>
+
 
</td>
 
</td>
 
<td>In the <b>C/C++ Projects</b> view, right-click a project and  
 
<td>In the <b>C/C++ Projects</b> view, right-click a project and  
Line 233: Line 229:
  
 
<tr>
 
<tr>
<td>Bold the name of the item being acted on (that is, the text), not the name  
+
<td>Bold the name of the item being acted on (that is, the text), not the name of interface control.</td>
of interface control.</td>
+
 
<td>Type the name <code><b>JanesProject</b></code> in the <b>Project&nbsp;name</b> field.</td>
 
<td>Type the name <code><b>JanesProject</b></code> in the <b>Project&nbsp;name</b> field.</td>
 
</tr>
 
</tr>
  
 
<tr>
 
<tr>
<td>For the results of a step, do not add the sentence,  
+
<td>For the results of a step, do not add the sentence, &quot;The New Project wizard opens.&quot;
&quot;The New Project wizard opens.&quot;
+
Instead, give the name of the dialog box or wizard that opens as an introductory phrase at the beginning of the next step.</td>
Instead, give the name of the dialog box or wizard that  
+
opens as an introductory phrase at the beginning of the next step.</td>
+
 
<td>
 
<td>
 
<ol>
 
<ol>
Line 252: Line 245:
  
 
<tr>
 
<tr>
<td>Begin a step, where applicable, by telling the user &quot;To &lt;do  
+
<td>Begin a step, where applicable, by telling the user &quot;To &lt;do this&gt;, &lt;do that&gt;.&quot;
this&gt;, &lt;do that&gt;.&quot;
+
  
<p>In other words, give the consequences of the action before you give the instructions
+
<p>In other words, give the consequences of the action before you give the instructions to perform.</p>
to perform.</p>
+
 
</td>
 
</td>
 
<td>To change tab settings, type a value in the <b>Value</b> box.</td>
 
<td>To change tab settings, type a value in the <b>Value</b> box.</td>
Line 262: Line 253:
  
 
<tr>
 
<tr>
<td>Do not use the word &quot;button&quot;, simply tell the reader to
+
<td>Do not use the word &quot;button&quot;, simply tell the reader to &quot;click &lt;<b>name of button</b>&gt;.&quot;</td>
&quot;click &lt;<b>name of button</b>&gt;.&quot;</td>
+
 
<td>Click <b>Next</b>.</td>
 
<td>Click <b>Next</b>.</td>
 
</tr>
 
</tr>
  
 
<tr>
 
<tr>
<td>Use the verbs &quot;select&quot; or &quot;clear&quot; for check boxes;
+
<td>Use the verbs &quot;select&quot; or &quot;clear&quot; for check boxes; bold only the name of the check box.</td>
bold only the name of the check box.</td>
+
 
<td>Select or clear the <b>Blank</b> check box.</td>
 
<td>Select or clear the <b>Blank</b> check box.</td>
 
</tr>
 
</tr>
  
 
<tr>
 
<tr>
<td>Do not use the word &quot;radio button&quot;.  
+
<td>Do not use the word &quot;radio button&quot;. Use &quot;click &lt;<b>name of radio button</b>&gt;.&quot;</td>
Use &quot;click &lt;<b>name of radio button</b>&gt;.&quot;</td>
+
 
<td>To change the background color, click <b>Custom</b>.</td>
 
<td>To change the background color, click <b>Custom</b>.</td>
 
</tr>
 
</tr>
  
 
<tr>
 
<tr>
<td>Do not instruct the user to &quot;click on&quot; something.  
+
<td>Do not instruct the user to &quot;click on&quot; something. Use &quot;click&quot;, &quot;right-click&quot; or &quot;double-click.&quot;</td>
Use &quot;click&quot;, &quot;right-click&quot; or &quot;double-click.&quot;</td>
+
 
<td>In the <b>C/C++ Projects</b> view, double-click your project.</td>
 
<td>In the <b>C/C++ Projects</b> view, double-click your project.</td>
 
</tr>
 
</tr>
  
 
<tr>
 
<tr>
<td>Do not instruct the user to &quot;click on&quot;.  
+
<td>Do not instruct the user to &quot;click on&quot;. Use &quot;click the &lt;<b>name of tab</b>&gt; tab.&quot;</td>
Use &quot;click the &lt;<b>name of tab</b>&gt; tab.&quot;</td>
+
 
<td>Click the <b>General</b> tab.</td>
 
<td>Click the <b>General</b> tab.</td>
 
</tr>
 
</tr>
  
 
<tr>
 
<tr>
<td>Do not use the word &quot;tree&quot;.  
+
<td>Do not use the word &quot;tree&quot;. Use &quot;Expand &lt;<b>something</b>&gt;, click &lt;<b>something else</b>&gt;.</td>
Use &quot;Expand &lt;<b>something</b>&gt;,  
+
click &lt;<b>something else</b>&gt;.</td>
+
 
<td>
 
<td>
 
<ol>
 
<ol>
Line 311: Line 295:
  
 
<tr>
 
<tr>
<td>Use the [http://en.wikipedia.org/wiki/Grammatical_person second person] when refering to the intended audience of the document.  Do not use "the user" or "the client" to refer to members of your audience.
+
<td>Use the [http://en.wikipedia.org/wiki/Grammatical_person second person] when referring to the intended audience of the document.  Do not use "the user" or "the client" to refer to members of your audience.
 
</td>
 
</td>
 
<td><strike>The user</strike> <em>You</em> can preview the files that are about to be committed from the comments page.</td>
 
<td><strike>The user</strike> <em>You</em> can preview the files that are about to be committed from the comments page.</td>
Line 319: Line 303:
 
<td>Consider having inline links to concepts that are Eclipse-specific.</td>
 
<td>Consider having inline links to concepts that are Eclipse-specific.</td>
 
<td>
 
<td>
<pre>
+
<pre style="white-space:normal">
&lt;p>This tutorial provides a step-by-step walk-through  
+
&lt;p>This tutorial provides a step-by-step walk-through of the features in the Eclipse  
of the features in the Eclipse  
+
&lt;a href="../concepts/concepts-2.htm">Workbench&lt;/a>. You will learn how to use these features by creating a &lt;a href="../concepts/concepts-12.htm">project&lt;/a>, then creating, running, and debugging a simple program.&lt;/p>
&lt;a href="../concepts/concepts-2.htm">Workbench&lt;/a>.
+
You will learn how to use these features by creating  
+
a &lt;a href="../concepts/concepts-12.htm">project&lt;/a>,
+
then creating, running, and debugging a simple  
+
program.&lt;/p>
+
 
</pre>
 
</pre>
  
<p>This tutorial provides a step-by-step  
+
<p>This tutorial provides a step-by-step walk-through of the features in the Eclipse  
walk-through of the features in the Eclipse  
+
<u>Workbench</u>. You will learn how to use these features by creating  
<span class="fakelink">Workbench</span>.
+
a <u>project</u>, then creating, running, and debugging a simple program.
You will learn how to use these features by creating  
+
a <span class="fakelink">project</span>,
+
then creating, running, and debugging a simple  
+
program.
+
 
</p>
 
</p>
 
</td>
 
</td>
Line 346: Line 321:
 
</tr>
 
</tr>
  
<!-- *************************** tables ************************ -->
+
</table>
  
<tr id="tables"><th>Tables</th><th>Example</th></tr>
+
===Tables===
 +
<table border="1" cellpadding="3" cellspacing="0">
 +
<tr id="tables"><th>Guideline</th><th>Example</th></tr>
  
 
<tr>
 
<tr>
Line 365: Line 342:
 
</td>
 
</td>
 
</tr>
 
</tr>
 +
</table>
  
<!-- *************************** CSS ************************ -->
+
===CSS Class Summary===
 
+
<table border="1" cellpadding="3" cellspacing="0">
<tr class="break" id="css"><th>CSS Class Summary</th><th></th></tr>
+
<tr id="css"><th>Guideline</th><th>Example</th></tr>
<td>
+
<tr>
<p>To call the book.css file, change the current markup from
+
  <td>
<br>
+
  <p>To call the book.css file, change the current markup from
<code>&lt;link rel="stylesheet" href="../book.css" type="text/css"></code>
+
  <br>
<br>
+
  <code>&lt;link rel="stylesheet" href="../book.css" type="text/css"></code>
to
+
  <br>
<br>
+
  to
<code>&lt;link rel="stylesheet" href="../../PRODUCT_PLUGIN/book.css" type="text/css"></code>
+
  <br>
<br>
+
  <code>&lt;link rel="stylesheet" href="../../PRODUCT_PLUGIN/book.css" type="text/css"></code>
(The help system will make the appropriate changes to the path at run time.)
+
  <br>
</p>
+
  (The help system will make the appropriate changes to the path at run time.)
 
+
  </p>
</td>
+
</td>
 
+
 
</tr>
 
</tr>
 +
</table>
  
<!-- *************************** graphics ************************ -->
+
===Graphics===
 +
<table border="1" cellpadding="3" cellspacing="0">
 +
<tr id="graphics"><th>Guideline</th><th>Example</th></tr>
  
<tr id="graphics"><th>Graphics</th><th>Example</th></tr>
 
 
<tr>
 
<tr>
<td>There are two types of graphics in the online help at present:
+
<td>There are two types of graphics in the online help at present: icons (which can be taken from the icon sets for the user interface) and screen captures.  
icons (which can be taken from the icon sets for the user interface)
+
<p>Icons are system-independent, so there are no reasons to give them class names or to be concerned about their file type.
and screen captures.
+
<p>Icons are system-independent, so there are no reasons to give
+
them class names or to be concerned about their file type.
+
 
</p>
 
</p>
<p>On the other hand, screen captures are system-dependent,
+
<p>On the other hand, screen captures are system-dependent, so it is important that different systems can display the appropriate screen captures. To do this, vendors need to be able to create a zip file of screen captures that the help system can display properly and automatically:
so it is important that different systems can display the
+
appropriate screen captures.
+
To do this, vendors need to be able to create a zip file of screen
+
captures that the help system can display properly and automatically:
+
 
</p>
 
</p>
 
<ul>
 
<ul>
Line 410: Line 382:
 
<li>Images should be no more than 650 pixels wide.</li>
 
<li>Images should be no more than 650 pixels wide.</li>
 
</ul>
 
</ul>
<p>The default setup for screen captures is:</p>
+
<p>Here are some general guidelines on taking screen shots:</p>
 +
<ul>
 +
<li>Ensure consistent look within a document: if a document has most of its screenshots done under a certain OS then additional screenshots must also be made under that OS. Ask a friend to capture them for you if it's hard for yourself.</li>
 +
<li>Use a default theme and not your custom colors and fonts.</li>
 +
<li>Trim the screenshot to only show the relevant information.</li>
 +
</ul>
 +
<p>Here is how to setup Windows XP for taking screen shots:</p>
 
<ul>
 
<ul>
<li>Windows XP</li>
 
 
<li>Display Properties &gt; Themes &gt; Theme: Windows XP</li>
 
<li>Display Properties &gt; Themes &gt; Theme: Windows XP</li>
 
<li>Display Properties &gt; Appearance &gt; Windows and Buttons: Windows XP Style</li>
 
<li>Display Properties &gt; Appearance &gt; Windows and Buttons: Windows XP Style</li>
Line 418: Line 395:
 
<li>Font Size: Normal</li>
 
<li>Font Size: Normal</li>
 
<li>Display Properties &gt; Appearance &gt; Effects &gt; Use the following method to smooth edges of screen fonts: Off (Not checked)</li>
 
<li>Display Properties &gt; Appearance &gt; Effects &gt; Use the following method to smooth edges of screen fonts: Off (Not checked)</li>
 +
</ul>
 +
<p>Here is how to setup Windows 7 for taking screen shots:</p>
 +
<ul>
 +
<li>Control Panel &gt; System &gt; Advanced system settings &gt; Advanced &gt; (Performance) Settings &gt; Visual Effects &gt; Select 'Custom' and uncheck 'Smooth edges of screen fonts'</li>
 
</ul>
 
</ul>
 
</td>
 
</td>
Line 429: Line 410:
 
</td>
 
</td>
 
</tr>
 
</tr>
 +
</table>
  
 
+
===Indexing===
<!-- *************************** indexing ************************ -->
+
<table border="1" cellpadding="3" cellspacing="0">
 
+
<tr class="break" id="indexing"><th>Guideline</th><th>Example</th></tr>
<tr class="break" id="indexing"><th>Indexing</th><th>Example</th></tr>
+
  
 
<tr>
 
<tr>
<td>Eclipse indexes its help files by looking at the text  
+
<td>Eclipse indexes its help files by looking at the text in the page and weighting titles over paragraphs. However, there can be times when you want the index to show text that does not display on the page. For example, if Eclipse uses its own terminology for a function, you might want users to be able to look up synonyms.  
in the page and weighting titles over paragraphs.  
+
However, there can be times when you want the index  
+
to show text that does not display on the page.  
+
For example, if Eclipse uses its own terminology for a function,  
+
you might want users to be able to look up synonyms.  
+
  
<p>To have the Eclipse index generate a hit for "autosave"  
+
<p>To have the Eclipse index generate a hit for "autosave" (a function that Eclipse has under another name) add a <tt>meta "keywords"</tt> tag before the &lt;/head> tag.</p>
(a function that Eclipse has under another name) add a  
+
<tt>meta "keywords"</tt> tag before the &lt;/head> tag.</p>
+
 
</td>
 
</td>
 
<td><pre>
 
<td><pre>
Line 452: Line 426:
 
</td>
 
</td>
 
</tr>
 
</tr>
 
<!-- ******* END style guide table -->
 
 
</table>
 
</table>
 
  
 
----
 
----

Revision as of 07:54, 12 May 2014

This document gives the style conventions to be used in Eclipse help. The Eclipse help has the following topic types: Tutorial (Getting Started), Concept, Task, and Reference. These topic types are based on the Darwin Information Typing Architecture (DITA) standards.

Topic Titles

GuidelineExample
A topic's title (heading) is marked with a heading value that matches the topic's position in the table of contents. The topic shown here is at the top level, so it is tagged as an <h1>. <h1>A Tour of the Workbench</h1>
The text in a topic's <title> must match the text in the heading. From concepts-2.htm:
  <title>The Workbench</title>
  ...
  <h1>Workbench</h1>
A topic's <title> must be unique to enable users to make a correct choice after a search.

Use sentence capitalization for all titles.

Results of searching for workbench:
  88% The workbench (concepts-2.htm)
  74% Workbench (ref-10.htm)
  70% The workbench (qs-02a.htm)

Better titles:

  88% What is the workbench? (concepts-2.htm)
  74% Workbench reference (ref-10.htm)
  70% Launching the workbench (qs-02a.htm)
Begin "task" and "getting started" titles with a gerund. Creating a project

Lists

GuidelineExample
Use a sentence fragment followed by a colon before numbered steps. To hide files by type:
Each numbered list item should include only one step.  
If you have an ordered list within an ordered list, use:


<ol type="a"></ol>

To do X:
  1. Step 1 text.
  2. Step 2 introductory text:
    1. Sub-step 1.
    2. Sub-step 2.
If you need to start an ordered list at a number other than 1, use


<li value="3">text</li>

  1. text
Each task topic should contain a reasonable number of steps.

"Reasonable" is a judgment call, and your freedom may be restricted by the complexity of the software. However, if you find that you are over 10 steps, see if you can break the steps into two sub-topics.

 
When describing menu items, use third-person descriptive verb tenses rather than imperative ones. Create a new file -> Creates a new file

Inline Markup

GuidelineExample
Elements names that appear in the GUI should be identified as such.

The standard convention for GUI elements is to display the name in a bold font. There are different ways this can be done:

  • Use <b> tags
  • Use the <strong> tags and expect that they will render as bold
  • Use <span> tags with different class types. For example:
    • <em class="UILabel">Preferences</em>
    • <span class="guibutton">OK</span>

The benefit of using class types is that the CSS file can then declare:

EM.UILabel {font-weight: bold;}

Or for a more elaborate display:

.guibutton { color: #000000; font-weight: bold;
 font-family: helvetica, sans-serif;
 background-color: #DCDCDC; padding: 1px 5px; 
 font-size: 10pt; border: outset 2px;
 text-decoration: none; line-height:175%; }
Preferences


OK

Topic Content

GuidelineExample
Provide a short description of what the user will accomplish. Files that you do not need to see can be hidden by file type in

the C/C++ Projects view.

(Note: That wording could be better—see below.)

Use the active voice. You can hide file types that you do not need to see in

the C/C++ Projects view.

(Note: That wording could still be better—see below.)

Wherever possible, make statements positive. In the C/C++ Projects view, you can display only the file types that you need to see.
Include no more than one task for each topic.  
Document how to access a feature through the menu bar, as opposed to using toolbar buttons or the context menu.

Avoid providing multiple ways to do something unless the menu-driven method is not always available. Project properties are an example of this: you can set project properties in the New Project wizard, but after the project is created you can set properties only by right-clicking on an individual project or in preferences (for all projects).

Click File > New > Project.

Note that the term "menu" is not used and that the menu path is in bold.

When you must provide multiple ways to do something use the format in the example.
  1. Do one of the following:
    • To set properties for future Standard Make projects, click Window > Preferences . Expand C/C++, click New Make Projects.
    • In the C/C++ Projects view, right-click a project, and select Properties. Select C/C++ Make Project from the list.
To instruct the user to make a choice, use the format in the example.
  1. Do one of the following:
    • To stop the build when an error is encountered, select Stop on error.
    • To continue the build even if an error is encountered, select Keep going on error.
When describing how to use the context menu (shortcut menu), instruct the user to "right-click <something> and select <something>."

Do not say, "From the context-menu, choose <something> as the term context-menu is not obvious to new users.

In the C/C++ Projects view, right-click a project and select Properties.
Bold the name of the item being acted on (that is, the text), not the name of interface control. Type the name JanesProject in the Project name field.
For the results of a step, do not add the sentence, "The New Project wizard opens." Instead, give the name of the dialog box or wizard that opens as an introductory phrase at the beginning of the next step.
  1. Click File > New > Project.
  2. In the New Project wizard, click C or C++.
Begin a step, where applicable, by telling the user "To <do this>, <do that>."

In other words, give the consequences of the action before you give the instructions to perform.

To change tab settings, type a value in the Value box.
Do not use the word "button", simply tell the reader to "click <name of button>." Click Next.
Use the verbs "select" or "clear" for check boxes; bold only the name of the check box. Select or clear the Blank check box.
Do not use the word "radio button". Use "click <name of radio button>." To change the background color, click Custom.
Do not instruct the user to "click on" something. Use "click", "right-click" or "double-click." In the C/C++ Projects view, double-click your project.
Do not instruct the user to "click on". Use "click the <name of tab> tab." Click the General tab.
Do not use the word "tree". Use "Expand <something>, click <something else>.
  1. Click Window > Preferences.
  2. Expand C/C++, click C/C++ Editor.
Use "type" instead of "enter."

("Enter" means "type <text> and press [Enter].)

In the Name box, type a name.
Use the second person when referring to the intended audience of the document. Do not use "the user" or "the client" to refer to members of your audience. The user You can preview the files that are about to be committed from the comments page.
Consider having inline links to concepts that are Eclipse-specific.
<p>This tutorial provides a step-by-step walk-through of the features in the Eclipse 
<a href="../concepts/concepts-2.htm">Workbench</a>. You will learn how to use these features by creating a <a href="../concepts/concepts-12.htm">project</a>, then creating, running, and debugging a simple program.</p>

This tutorial provides a step-by-step walk-through of the features in the Eclipse Workbench. You will learn how to use these features by creating a project, then creating, running, and debugging a simple program.

Do not use Eclipse implementation details such as plug-in ids, component names, project names, or version numbers in user documentation. Such content is fine in plug-in developer (ISV) documentation. Keep in mind the end user may be using a branded product with a different version number. Since Equinox 3.3, you can...You can...

Tables

GuidelineExample
Declare tables consistently.

<table border="1" cellpadding="3" cellspacing="0">

Set the vertical alignment for rows to "top" in the CSS file.

tr { vertical-align: top; }

CSS Class Summary

GuidelineExample

To call the book.css file, change the current markup from
<link rel="stylesheet" href="../book.css" type="text/css">
to
<link rel="stylesheet" href="../../PRODUCT_PLUGIN/book.css" type="text/css">
(The help system will make the appropriate changes to the path at run time.)

Graphics

GuidelineExample
There are two types of graphics in the online help at present: icons (which can be taken from the icon sets for the user interface) and screen captures.

Icons are system-independent, so there are no reasons to give them class names or to be concerned about their file type.

On the other hand, screen captures are system-dependent, so it is important that different systems can display the appropriate screen captures. To do this, vendors need to be able to create a zip file of screen captures that the help system can display properly and automatically:

  • Screen captures must be ".png" files.
  • Image declarations must not specify image sizes.
  • Image declarations should have "alt" attributes (this is an accessibility feature).
  • Image declarations may have a <title> attribute.
  • Screen captures should be taken at the minimum supported resolution of 1152x864.
  • Images should be no more than 650 pixels wide.

Here are some general guidelines on taking screen shots:

  • Ensure consistent look within a document: if a document has most of its screenshots done under a certain OS then additional screenshots must also be made under that OS. Ask a friend to capture them for you if it's hard for yourself.
  • Use a default theme and not your custom colors and fonts.
  • Trim the screenshot to only show the relevant information.

Here is how to setup Windows XP for taking screen shots:

  • Display Properties > Themes > Theme: Windows XP
  • Display Properties > Appearance > Windows and Buttons: Windows XP Style
  • Color Scheme: Default (blue)
  • Font Size: Normal
  • Display Properties > Appearance > Effects > Use the following method to smooth edges of screen fonts: Off (Not checked)

Here is how to setup Windows 7 for taking screen shots:

  • Control Panel > System > Advanced system settings > Advanced > (Performance) Settings > Visual Effects > Select 'Custom' and uncheck 'Smooth edges of screen fonts'
<img border="0" src="../images/Image201_fillet" alt="Define a New File Type dialog">
Screen captures should generally be PNG-8 (8 bit color) to keep image sizes small. If a particular screen shot uses enough color to warrant additional color depth, use PNG-24. Use your judgement. Start with PNG-8, and if it looks bad then use PNG-24 instead.

Indexing

GuidelineExample
Eclipse indexes its help files by looking at the text in the page and weighting titles over paragraphs. However, there can be times when you want the index to show text that does not display on the page. For example, if Eclipse uses its own terminology for a function, you might want users to be able to look up synonyms.

To have the Eclipse index generate a hit for "autosave" (a function that Eclipse has under another name) add a meta "keywords" tag before the </head> tag.

<meta name="keywords" content="autosave">

Back to Eclipse Documentation

Copyright © Eclipse Foundation, Inc. All Rights Reserved.