ICG Usage and Style Notes

This page is about the “rules” we follow in ICG documentation. It is very much “under construction”. Items are added as bullets as wanted/needed by documentation authors.

• When writing the first line of the verbiage that describes a command:

  • Use the imperative mood (“Create a block”), not the indicative (“Creates a block”).
  • If at all possible, keep the first sentence of the description below 10 words. If it is too long, when it is listed along with its siblings on a table of commands, it will be truncated with ellipses (…).
  • capitalize the first letter of both the main description and all keyword descriptions. Try VERY HARD to use complete sentences at all times. There will be cases when neither is appropriate (for instance, “\(x\)-component of displacement” could be the right description of a keyword, but it would violate both of the aforementioned, and that is ok but to be avoided if possible).
  • all descriptions (since they are complete sentences) should have a period at the end.
  • always use “Get/Set” for read/write operations in FISH (in general these will be first in the descriptive line, so capitalize)

• For user interface elements:

  • keystroke commands are offset using the role :kbd: (… press Ctrl + spacebar to access the inline help facility…). Use “+” to indicate key combination.
  • menu commands are offset using the role :menuselection: (… accessed using the Tools ‣ Check Modifications… menu command …). (Right now these format identically to keyboard commands, but that could change so it is worth marking them accurately.) Use “–>” to join multiple menu levels/items as needed. DO INCLUDE ellipses if they appear in the label of the menu command.
  • text-labeled buttons use :button: (… press the OK button).
  • icon-labeled buttons should parenthetically try to show the icon (… use the Execute button ( ) to run the data file … ). The button should be “named” in text to match whatever its tooltip indicates. You’ll want to use a substitution to do this.
  • A named item in the interface should be italicized. So: The Console pane, the Handle, the Edit toolbar, etc.
  • A label or other text appearing in the interface, particularly with regard to other interface elements, should be quoted (… check the “Include Project Files” checkbox … ; … refer to the “Attributes” section in the Control Panel…).

• For examples of any kind:

  • These should ALWAYS be standalone documents; they should not appear embedded in a description section (inserting them within a descriptive section via toctree will add them to the navigation tree as needed).
  • Use a “prefix” to be used for tagging all local resources within the example (figures, equations, tables, etc.)
  • only include one main data file at the end of the example
  • make sure the example is registered on the table index at the end of the help file as needed in under