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?
  • Use typewriter text (space indent) for Analytica code, e.g.
 Variable X := Y + Z
  • For results of Analytica expressions, use right arrow to show result:
 10^5 -> 100K
  • Use Suffix notation, unless there is a reason not to.

Conventions for explaining functions and their parameters

For Function parameter declarations, we now use type writer text, e.g. 

MakeDate(year: Coerce Atomic Positive; month, day: Optional Coerce Atomic Positive)

One problem is that these sometimes extend over the right margin, and lose the end. The full declarations may be good for detailed documentation, but are intimidating to non-expert users, and hard to read. So I (MH) propose that we introduce simple functions with parameters in their subheading like this:


Conventions

  • Use lower case for parameter names.
  • Omit qualifiers
  • Omit optional rarely used parameters
  • [, i]: Means parameter is optional. (Don't admit that for indexes that are highly recommended, as in Sum(x, i)).
  • Argmax(x, i...): Ellipsis means multiple parameters are allowed.

Use these conventions for naming parameters that are not "named" in syntax, to indicate what is expected:

  • x, y, z: Numbers that may be scalar or array.
  • i, j, k: Identifiers of Index variables
  • t, t1, t2: Text values (numbers will be coerced to text)
  • a, b, c: An expression that may evaluate to anything: Scalar or array, number or text, NAN, or reference.
  • p, q: A probability, a number between 0 and 1.
  • r: A reference
  • v: Identifier of variable.
  • e: An expression that may evaluate to anything
  • expr: An expression (not evaluated before calling function)
  • obj: Identifier of Object (any Class)
  • attrib: Identifier of Attribute

Most named parameters that are not meaningful (unlike mean, min, mode) already follow these conventions. If any do not, we should consider changing them so they do.

  • Provide a page explaining these conventions, linked to from every function description.

Each function description should have:

  • Title of section (usually 3= level) includes name of function and most common parameters.
  • Brief description of at least simple case use.
  • Example(s)
  • More complex uses, if any
  • Requirements: Expectations or constraints on parameters.
  • For functions with many parameters, give them in bulleted list, explaining each.
  • Syntax: Near bottom using (slightly cleaned) declaration syntax.

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 ()[].
Comments


You are not allowed to post comments.