GMAT Documentation Style Guide

Overview

The GMAT Style Guide governs the style of all official GMAT end-user documentation, including training material and the User Guide. When writing documentation for GMAT, use the Microsoft Manual of Style, Fourth Edition as a baseline. This book covers issues such as wording and tone, as well as proper ways to refer to screen elements like menu items and dialog boxes. The rest of this guide highlights parts of the Microsoft manual, but if there is any confusion, reference that document. Any exceptions will be clearly labeled. An internal PDF copy of the book is available on the GMAT network share, at \\mesa-file\595\GMAT\Resources\Microsoft Manual of Style - Fourth Edition.pdf. There are also two hard copies in possession of Steve and Joel. The official GMAT documentation set is written in DocBook 5, an XML-based format. DocBook 5: The Definitive Guide is a comprehensive reference to DocBook and is available online. We use the XMLMind XML Editor to write the documentation, then the Docbook XSL Stylesheets and a variety of other tools to convert from DocBook to a variety of other formats, like HTML, PDF, and CHM (Microsoft's HTML Help). Tips for writing DocBook code are included in each section below for reference.

General Style

See the Microsoft Manual of Style.

Audience Assumptions

GMAT's documentation should explain concepts that are unique to GMAT itself, or are otherwise little-known to GMAT's primary user base. It should not seek to educate the reader on astrodynamics, spacecraft design, or numerical algorithms. Of course, if the documentation in question is intended for educational purposes, this guideline does not hold.

Document Configurations

The formal GMAT documentation can be built as a full User Guide or as a smaller Training Manual. Textual differences between the two can be indicated in DocBook by applying the condition attribute to a given element. The following values are recognized:

• condition="ug"
• condition="tm"

For example, consider a sentence that must read differently depending on the configuration: "The document title consists of the following sections." In Docbook, this can be written as shown:

If the entire paragraph is different, the condition attribute could also be applied directly to the para element. When the document is built, the appropriate text will be chosen automatically.

Terminology

Terminology refers to the appropriate words for elements of the GMAT interface, such as the GMAT window, the menu bar, the Resources tree, and the Spacecraft dialog box. The Microsoft Manual offers a wide range of instructions for how to refer to interface elements. Here's some of the more commonly-used rules:

• The mouse moves the pointer, not the cursor.
• Use click to refer to the left mouse button, and right-click to refer to the right mouse button. In general documentation, the first instance can be written as right-click (?-click on the Mac).
• Use click for buttons, select and clear for check boxes, type and select for combo-boxes, and type or enter for text boxes.
• Order the text to match the order of focus: "In the Resources tree, expand the Output folder."
• Here's an example for a GUI instruction: "On the Tools menu, click Options, and then click the View tab."
• The three tree views are styled as: Resources tree, Mission tree, Output tree.
• When talking about fields and parameters, use the terms "get", "set", "gettable", and "settable". Don't use "read/write".

Procedures

• Procedures should consist of a series of discrete actions that all lead to a common goal. Keep them as short as possible to get to the next incremental goal; don't use one long procedure for a lengthy process. Procedures should be numbered, use the imperative voice, and end with periods. Here's an example:
• Open GMAT.
• Open the DefaultSC resource and click the Attitude tab.
• In the Attitude Model box, click Spinner.

In DocBook, procedures should be written with the procedure element:

Figures

Figures should be used to illustrate key concepts and to show the results of a complex procedure. In general, figures should contain only as much detail as necessary. For example, don't show the entire Spacecraft dialog box if you are only referencing the Epoch box. Large figures should be placed immediately below the text that references them, on their own lines, with a numbered caption below the image. See Figure 1 for an example.

Spacecraft default Cartesian state.png

Figure 1: Spacecraft default Cartesian state

Screenshots should always be in the PNG format. Drawings and other figures that you create should be in a vector format, like SVG. Photographs can be in the JPEG format. In DocBook, figures with a title should use a figure element, with a nested screenshot element if the image is actually a screenshot:

Figures that don't need a caption should instead use the informalfigure element:

All images should have the following attributes, regardless of figure type.

However, if small images are turning out overblown in the resulting PDF, try using this syntax, adjusting the scale attribute as necessary:

Small images can be used to illustrate icon names, if appropriate. For example, the following procedure may be used the first time the user clicks Run.

1. On the toolbar, click Run ().

Inline images are written in DocBook like so, with an inlinemediaobject instead of a figure wrapper:

<inlinemediaobject>
    <imagedata align="center" contentdepth="8pt" width="1em" fileref="..."/>
</inlinemediaobject>

The sizing values above seem to work well with the default font settings (11-point Garamond).

Headings

Minimize the number of nested headings. A how-to article might have a single heading with the title of the article. A long tutorial might have two levels of headings: a title and top-level sections. Use title case for all headings This is a difference from the Microsoft Manual of Style to support legacy documentation with title-case headings. This usage is supported by the Apple Publications Style Guide. In DocBook, tutorials and how-tos both use the chapter element and sections use the section element:

Cross-References

References to other content should use hyperlinks where possible. If used multiple times within a self-contained topic (such as a how-to or tutorial), use a cross-reference for the first reference only. In DocBook, external links should use the link element:

Links between parts of the same document can either use the link or xref elements, as appropriate. Both forms use IDs for linking, which means you must first tag the destination with an xml:id attribute. The link element allows you to include your own link text, while the xref element automatically uses the name of the target. An example, the following code defines a section, then links to the chapter in two ways. The result is shown below the code.

My Section Title

See the first section for more information. See My Section Title for more information.

Equations

Simple equations may be used in-line. Complex or particularly important equations should be positioned centered on their own lines. Right-aligned numbers may be used for later cross-referencing. In DocBook, simple equations can be written in free text as follows (assuming an inline equation here):

More complex equations should be encoded as MathML. You can either write MathML by hand (see the Wikipedia article for syntax) or with a math editor that can export as MathML. OpenOffice.org and LibreOffice both have editors that will work for this purpose. Numbered equations should use the equation element:

Equations that don't need numbering can use the informalequation element instead. Inline equations should use the inlineequation element.

Typographic Conventions

Use the following conventions for different types of text elements. For exact font specifications, see the Visual Style section. There is an extensive list of other styles in the Microsoft Manual. Those styles should apply unless explicitly different in the table below. To add to this table, consult the DocBook Reference for available elements.

Commands, Parameters, Resources, and Fields

It can be confusing to know how to format the names of commands and resources and their parameters and fields. The general rules are as follows:

• When referring to a concept (like a spacecraft in general), use normal text.
• When referring to the GMAT command, resource, parameter, or field in general, use <guilabel>.
• When referring specifically to the GUI, use the <guilabel>.
• When referring to an example of scripting, use <code>.

And now some examples:

Tables

Formal tables that are referenced in the text should be centered, with thin black borders, with a top caption. Informal tables (for example, to display a list of data to be entered) do not need a caption. Here's an example of a formal table: Table 1: Default coordinate systems

Code Examples

Long code examples should use the <programlisting> and <code> tags, and be contained within an <example> tag as appropriate. When writing GMAT code, the following rules apply:

• Write the minimum amount of scripting necessary to illustrate the point.
• Don't use the "GMAT" prefix when setting resource properties.
• Don't end script lines with semicolons.
• Indent each level by 4 space characters.
• Quote all strings.
• Note any missing steps with a comment.
• Put a space between list elements or parameter lists (after the comma).
• Separate simple resource creation statements from those that have extra configuration.
• Name resources in CamelCase with an "a" or "an" prefix: aSpacecraft, aPropagator, anImpulsiveBurn.
• If the example is runnable, validate it.

See the following example:

Example Common Task

Common Tasks are short documents that explain how to perform a specific procedure or use a specific feature. They are not as expansive as a tutorial, and should contain one or two introductory paragraphs and a single set of procedures. A general how-to topic may be broken into sub-topics, each with its own introduction and procedure. How-tos should not assume a particular mission or base state for GMAT, but instead should illustrate the procedure using the simplest base state that would normally be encountered by the user. Whenever possible, use the default mission as the base state. The title should start with a gerund, not with the phrase "How to". An example how-to is shown below.

Reporting Data During a Propagation Span

You can report data at each integration step in the mission sequence by creating a ReportFile resource and adding data to it. Starting from the default mission:

• On the Resources tree, right-click the Output folder, point to Add, and click ReportFile.
• Double-click the ReportFile1 resource.
• In the Parameter List area, click Edit.
• In the Selected Value(s) list, click DefaultSC.EarthMJ2000.X and click <- to remove it from the list.
• In the Object Properties list, click Altitude and click -> to add it to the Selected Value(s) list.
• Add DefaultSC.A1ModJulian to the Selected Value(s) list if it doesn't already exist.
• Click OK, then in the ReportFile - ReportFile1 dialog box, click OK again.
• Click Run. To view the generated report, on the Output tree, double-click ReportFile1.