Document style guide

Language

• Use active voice: "Analytica displays an error message" not "An error message is displayed."

• Use imperative for advice, like this, or a series of steps to follow.

• Refer to the reader or user as "you", and the writer or Lumina as "we", as in "We invite you to email us your comments" not "The reader is invited to email Lumina their comments.". In the wiki where multiple authors might make this ambiguous, you might say "Please email Lumina your comments." where "you" is the reader.

• Use bulleted lists wherever appropriate, like this.

• Use numbered or lettered lists only where items are intrinsically ordered, as in a series of steps.

• Order functions and features in lists (or as sections in documentation), with the most frequently used or easiest to understand first, and most obscure last. That way, (a) when you are scanning to find what you want, you will find it sooner on average, and (b) if you ar reading sequentially, you will read the easiest stuff first, preparing you for the harder stuff. Alphabetic ordering adds little: If you know the name of the function (or whatever), it's faster to use electronic search (or the index in a printed version).

• In long lists, group related or similar items together under subheads.

Text style

• Use bold for names of menus and menu options -- e.g. Select Graph Setup... from Result menu.
• Use italic for names of documents -- e.g. Analytica User Guide.
• Use italic for emphasis -- e.g. "Do not use italic just because you feel like it."
• Use bold when introducing or defining key concept (bold italic in PDF and Word) -- e.g. "array abstraction means treating arrays as objects without having to worry about their dimensions -- except when you need to."
• Can we find a way to make tables more elegant? Avoid horrible double edges to cells?

Organizing documents with multiple pages

• Organize the pages into a set of "documents" or "sections", such as "What's new in Analytica 4.0?", "Analytica Reference Guide", "Analytica FAQs", "Analytica libraries".

• Organize each document or section as a tree hierarchy -- i.e., where each page has a single parent -- although there may, of course, be many cross-references. A tree makes it easier for you to understand the organization, and go through all pages at a given level. It also makes it easier to generate a sequential PDF or printed document if we need to.

• Show ancestor list (a.k.a. "bread crumbs") at the top of each page -- i.e. a list of links to parent, grandparent etc. For example, page SolverInfo should show

Analytica Reference Guide > Enhancements to Optimizer in Analytica 4.0 This helps you see where you are and lets you quickly move up one or more levels.

Organizing a page

• Keep page names as short as reasonable.

• Show ancestor list (see above)

• Don't use higher level headings than you need -- e.g. if you only need one level, use ===. If you need two, use == and ===. Only use = if you have at least three levels of subhead in a page.

• Common subheads:
  • Examples
  • Tips
  • See also
  • Enhancement requests
  • Documentation requests

Analytica code

Common conventions

• Capitalize identifiers of objects and functions.
• Use uppercase for key words, like IF...THEN.. ELSE, BEGIN END, FOR.
• Use lowercase for identifiers of formal parameters and local variables in a function.
• Indent multiline Definitions.
• Add a space around +, -, =, <, <=, >=, >, <> operators, not around "*", "/", and "^".
• Add a space after ",", but not around ()[].

Variable and parameter name conventions

• Use I, J, K for Index variables in examples.
• Use X, Y, Z for numerical scalar or array variables.
• Use S, T for text values.
• Use B for Boolean or truth value.
• Use P, Q for probabilities.