Don’ts

  • Don’t use any of the pronouns “I” “my” “We” “our” “You” “your”

  • Don’t use hard carriage returns; turn on wrap, dammit!

  • Don’t use asterisk ( * ) for anything but italicizing or bold (not section underlining, not footnotes, etc.— definitely not on lists).

  • Don’t use :lkwd: (or :lint: or :lflt or any role starting with “l”); use ``word`` instead.

  • Don’t use relative paths with dots; use explicit paths from root and only use relative going downward.

  • Don’t use :flag:; use :flag3: for inline comments; also, indicate authorship with initials (e.g., “CS:”) in the comment.

  • Don’t indent lists (ordered or unordered) from the preceding level.

  • Don’t put an anchor above a directive (do not use .. _linklabel: when you can use :name:); do put an anchor above a title/subsection as needed. Especially important for figures!

  • Don’t use pipe ( | ) for line breaks or to add vertical space; use |br| (almost anywhere, including a table) for a single line break.

  • Don’t use :align: center on .. figure:: directives. DO use it (if centering is needed) on .. image:: directives (though generally, if something is going in the middle of the page, use .. figure::…).

  • Don’t use “click here” or “see this figure” (or similarly ambiguous, non-indicative text) as the label text of a hyperlink.

  • Don’t use the word “pane” to refer to anything in the user interface.

  • NEVER EVER USE TAB. EVER.

Explanations

i Pronouns

For better or worse, all Itasca software documentation since the dawn of time is written in third person passive voice. This means the aforementioned pronouns should never appear. Imperative voice is used, but “you” for that case should always be implied:

BAD:  You must open the document in Word.
GOOD: Open the document in Word.

i Hard Returns

Finding whitespace errors is much harder in documents that have used hard returns. Also, for those who are not using hard returns (wrap is ON in their editors), hard returns can be visually difficult as well.

Two reasons: (1) underscores are converted to hyphens in html output, which makes backtracking to the anchor text from html ambiguous, and (2) underscore is used in reST markup a lot; hyphen isn’t. The *.rst files are easier for a human to parse when underscore is reserved for markup purposes.

i asterisks (*)

reSt overuses the asterisk character (*), which facilitates making mistakes with it. To avoid this, as a usage convention ICG docs only use asterisks for putting words in italic (*italics*) or bold (**bold**) typefaces.

i Use of the “l” roles

This is outdated usage, pure and simple. It was invented to allow for presentation of literals without triggering warnings in Sphinx and, secondarily, to allow color-coding of syntax. As the latter is no longer done in general body text, it is easier to use double-ticks for any literal.

BAD: :lint:`3`  or  :lflt:`3.33`  or  :lstr:`fred`  or  :lkwd:`label`
GOOD:  ``3``    or    ``3.33``    or    ``fred``    or    ``label``

i Dots in paths

Paths are used predominantly for figures and dat files. When a path starts with a “/”, Sphinx appends the documents root at the slash (the root is two folders up from the location of the make.bat file). By comparison, paths starting without a “/” are understood to be relative to the current document location. Dots allow specification of a “go-up-and-then-go-down” path, but why? Consider:

BAD: ../../../../../wad/wallzone/doc/manual/zonejoint_manual/cmd_zone.joint*
GOOD: /wad/wallzone/doc/manual/zonejoint_manual/cmd_zone.joint*

i the :flag: role

Again, this is outdated usage. The role :flag: will type its contents in red (← used :flag: there). Formerly, this was used to “flag” an element in the page that needed fixing—a sort of aggressive comment. See the comment topic for proper metatextual messaging.

BAD:  :flag:`Someone will need to fix this equation.`
GOOD: :flag3:`CS: Someone will need to fix this equation.`

i pipe (|)

This is another outdated usage. Early ICG docs used pipe ( | ) to add vertical spacing. This should never be necessary anymore. Please get help if it seems necessary to add vertical space in a document. In the meantime, there are cases where single-spacing of lines may be needed. Though this may be achieved in reST by placing | at the start of each line, in ICG docs this is done by placing |br| (an ICG custom replacement) at the end of each line.

i pane

This is outdated terminology. The term pane was formerly applied to elements in the user interface. This is no longer true. Avoid mentioning containers in the interface if possible. If it isn’t possible, then use the word “workspace” to refer to any area where a user will do work. Whenever possible, refer to the object IN the window (data file, plot, sketch), not the window itself (editor, plot pane, sketch pane). The Model workspace is the one usage that is probably better than the alternative.

BAD: Open a new data file in the Editor.
GOOD: Open a new data file.
BAD: View the model results in the plot pane.
GOOD: Create a new plot to view model results.
BAD: When working in the Building Blocks pane ...
GOOD: When working with a Building Blocks set in the workspace ...