Document style guide

Language

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

• Use imperative in steps to follow or advice, like this.

• 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 -- rather than alphabetic or random. That way (a) the reader is most likely to find what they want more quickly and (b) if they read sequentially. If users know the name of the function (or whatever), they can use search (or the index in a printed version) to find it, so alphabetic ordering adds little.

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

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.

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 never having to say you're sorry"
• Can we find a way to make tables more elegant? Avoid horrible double edges to cells?