Document style guide

Language

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

• It's OK to refer to Analytica as "it": "When you click the button, it displays the dialog box." Mention "Analytica" by name rarely. Use "it" wherever it's unambiguous. (In Analytica documentation, "it" is rarely ambiguous.)

• 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.

• When you introduce a list, say "These are options for parameter X:" not "The following are options for parameter X."

• Use present not future tense for what Analytica does: "When you click OK, it closes the dialog." not "When you click OK, Analytica will close the dialog."

• Use "parameter" not "argument" for the items passed to a function calls.

Lists

• Use bulleted lists wherever appropriate, like this.

• Use numbered or lettered lists only where items are intrinsically ordered, as in a series of steps that would not work in a different order.

• Order items in a list (or sections in chapter) from the easiest or most commonly used first to the most obscure. Hence,
  • when scanning, you will find what you want sooner on average, and
  • when reading, you will read the easiest stuff first, making it easier to understand the harder stuff that comes later.

• 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 similar or related items together under subheads.

Typographic Conventions and FrameMaker Character Code Tags

When writing documentation use the followins style conventions.

In FrameMaker carefully adhere to the character tags specified here. There are some character tags that currently apply the same font attributes. Even so, you should still use the proper character tag, so that, in the future, is we decide to change the look of parameters we can sinmply change the definition of the "parameter' character tag and not have it affect other items.

Type of Text	Typography	FrameMaker Character Tag
Special terms where introduced and explained, with link to Glossary	Bold Italic	Bold Emphasis
Window titles, menus, menu items, dialog box titles, panel titles, and button labels	Bold	UI Object
Analytica object identifier or title, including variables, functions, and modules, in text, but in a code fragment.	Bold and Capitalized	UI Object
Checkbox labels and other input labels, like the like the Edit Attributes setting for the Preferences dialog	Italics	UI Label
Key on keyboard	Italics: "Press Enter"; control-e	Emphasis
Function names	Bold and Capitalized with trailing parens, "()": Argmax()	Function
Formal parameter names	bold lowercase or "camelCase" to distinguish words when necessary: x, start, stepSize	Parameter
Code and script examples, expressions and variable definitions	Fixed width (Courier) font	Code
True and False	When used as Boolean values these should be in code format. (Courier)	Code
If...Then...Else	Code format(Courier)	Code
The word "variable"	When it is used in the normal sense, there is no special typography. However, if we are referring to a special Analytica term, such as "Variable node" or "Chance Variable" then it should be capitalized. General rule: if the term has a special Analytica meaning, then capitalize it	Default font
The word "attribute"	This is similar to the word "variable': When it is used in the normal sense, there is no special typography. However, if we are referring to a special Analytica term, such as "Analytica Variable Attributes" then it should be capitalized.	Default font
Special terms like"Edit" mode	Capitalize: Edit mode, Browse mode	Default font
Document names	Italics and Capitalized	Emphasis

Analytica code

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 -- four spaces per indent.

• Spacing conventions in code and expressions,
  • Add a space around lower precedence operators +, -, =, <, <=, >=, >, <>
  • no space around higher precedence operators "*", "/", and "^".
  • A space after, but not before separators ",", ":" and ";"
  • No space before or after around parens or brackets: ()[]{}, e.g.

a + b*c/(d - e)2 AND (x < y) OR (u = v)
Sum(10 + X, I) - (1 + X^2)/(X - 1)

• Code examples should be indented modestly; use the "code' paragraph tag in FrameMaker that indents 1/4"

Other Style Conventions

• For results of Analytica expressions, use right-arrow "&rarr;" to show result:

 10^5 → 100K

• Use Suffix notation, unless there is a reason not to.
• Spacing for functions in subheads, in syntax, and anywhere:
  FunctionName(param1, param2)
  not
  FunctionName ( param1, param2 )
  i.e., space after "," or ":", but not before or after "(" or ")".
• We allow multiple functions to be defined in the same section when they are closely related.
  No need for extra subheads "CDF(x)", "PDF(x)" just above Syntax sections.
• All function definition sections must use a Heading2 paragraph tag for the function title for the section.
• Make the distinction between nodes and objects. A node is the visual representation of an object;
  an object can have multiple nodes (e.g., by creating aliases or having input and output nodes).

Conventions for explaining functions and their parameters

The heading for the section of documentation on a function should contain the name of function and the most common parameters, without qualifiers. In some cases, we might include multiple functions in one section and therefore in the same heading, e.g.

PDF(x) and CDF(x)

Each section describing a function (or functions) should contain a complete spec of its parameters, usually near the end of the section, with a format like this:

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

Note that the subhead Parameter types is a link to a page that explains the meaning of the parameter types and qualifiers.

Conventions: We should use the recommended name for each qualifier rather than its deprecated synonyms. We should omit "Atomic" which is of more interest to the implementation of the function that to the user of the function.

Use these conventions for naming parameters that are not "named" in syntax, to indicate what type 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

What's new?

• Every page linked to from What's new, should have a link at the top:

What's new in Analytica 4.0 >

• Every function shd be annotated one of:
  • (Added in 4.0)
  • (Modified in 4.0)
  • (Unchanged in 4.0)

(But, we won't be adding much stuff that's unchanged until we've completed the stuff that has changed.)