DocumentationGuidelines/StyleGuidelines

Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.

Introduction

This document gives the style conventions to be used in Eclipse help. They have been updated and modified to fit the wiki markup. Many of the rules still apply to writing using the wiki. The Eclipse help guidelines are very specific to the help system, however, wiki documentation can end up in a variety of formats, so should try to use a more general approach to writing.

Eclipse help is very influenced by DITA the Darwin Information Typing Architecture (DITA) standards. The wiki style guides complement and extend the Eclipse Help guides to a broader medium.

Eclipse Help Style Guidelines

For more details on general help writing, see the Eclipse_Doc_Style_Guide.

Section Titles

A section's title (heading) is marked with a heading value that matches the sections position in the table of contents. The seciton shown here is at the top level, so it is tagged:

= A Tour of the Workbench =

Text in a Section

The text in a section's title must match the text in the heading.

A section's title must be unique. This helps with exports to the eclipse help system 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
• 74% Workbench
• 70% The workbench

Better titles:

• 88% What is the workbench? (concepts-2.htm)
• 74% Workbench reference (ref-10.htm)
• 70% Launching the workbench (qs-02a.htm)

Task and Getting Started Sections

Begin "task" and "getting started" titles with a gerund.

Lists

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:

# Step 1 text.
# Step 2 introductory text:
## Sub-step 1.
## Sub-step 2.

Result 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

Need Example here for wiki.

Need result here.

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.

Inline Markup

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.

For example:

Need Example or Template that renders

Topic Content

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.

Wording
The 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.

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.

Topics should include no more than one task. If you find yourself writing about more than one topic, then either a sub section or a new section needs to be created.

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:

Admonitions

There are five types of admonitions:

• caution
• important
• note
• tip
• warning

All of the admonitions have the same structure: an optional title followed by paragraph-level elements. To make a paragraph into an admonition, use the special admonition template. A short title and a longer descriptive paragraph are recommended!

What you type	What you see
{{note|A title|Here is more information about this tip.}}	A title Here is more information about this tip.

Indent the initial and second paragraph by one space, to ensure that the box aligns correctly.

These are the standard types of admonition:

What you type	What you see
{{note|This is a note|Informational paragraph that tells more about what is going on.}}	This is a note Informational paragraph that tells more about what is going on.
{{tip|This is a tip|Informational paragraph that tells more about what is going on.}}	This is a tip Informational paragraph that tells more about what is going on.
{{important|This is important|Informational paragraph that tells more about what is going on.}}	This is important Informational paragraph that tells more about what is going on.
{{caution|This is a caution|Informational paragraph that tells more about what is going on.}}	This is a caution Informational paragraph that tells more about what is going on.
{{warning|This is a warning|Informational paragraph that tells more about what is going on.}}	This is a warning Informational paragraph that tells more about what is going on.

Source Code Examples

Eclipsepedia has an extension tag for allowing syntax highlighting of source code.

Java

<source lang="java">
// Get XML Schema Information for the Document
XSModel schema = getGrammar();

DynamicContext dc = setupDynamicContext(schema);

String xpath = extractXPathExpression(xqFile, inputFile);
String actual = null;

</source>

Renders as:

// Get XML Schema Information for the Document
XSModel schema = getGrammar();
 
DynamicContext dc = setupDynamicContext(schema);
 
String xpath = extractXPathExpression(xqFile, inputFile);
String actual = null;

XML: plugin.xml or other xml related

XML formatting should follow these particular guidelines:

• Indent with 3 spaces for each element node
• Make the format so that it is human readable at 80 columns

The output could be generated to muliple sources so what looks fine in a web page, may not render the same in a PDF or other media format.

Format to least common denominator
Since output could go to the web, eclipse help, wiki, pdf, or ebook. It is best to try and format to the least common denominator. Assume for XML formatting that 80 characters wide is the max available.

<source lang="xml">
<extension
       point="org.eclipse.ant.core.antTasks">
   <antTask
     class="org.eclipse.wst.xsl.core.internal.ant.XIncludeTask"
     headless="true"
     library="lib/xinclude.jar"
     name="xsl.xinclude">
   </antTask>
</extension>
</source>

Renders as:

<extension
       point="org.eclipse.ant.core.antTasks">
   <antTask
     class="org.eclipse.wst.xsl.core.internal.ant.XIncludeTask"
     headless="true"
     library="lib/xinclude.jar"
     name="xsl.xinclude">
   </antTask>
</extension>