Document style guide

Revision as of 17:19, 27 October 2010 by Max (talk | contribs)

We intend these guidelines to apply to all writing within and about Analytica, including:

  • Inside Analytica
    • Dialogs, warnings, and error messages
    • Internal documentation
    • Example Analytica and AWP models distributed with Analytica
  • Outside Analytica
    • The Tutorial and User Guides, including the Optimizer and ADE User Guides
    • Analytica Wiki
    • Lumina web site
    • User guides and documentation for Analytica applications
    • Consulting proposals and reports.


Language

  • Use active voice:
    • "Analytica displays an error message" not "An error message is displayed."
    • "You can use Function F to ... " not "Function F may be utilized to ..."
  • Use imperative for advice, like this, or a series of steps, e.g.
  1. Select Graph setup from Result menu
  2. Check X option
  3. Click OK
  • Refer to the reader or user as "you", and the writer(s) 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 a wiki, where multiple authors might make this ambiguous, write "Please email Lumina your comments." where "your" refers to the reader.
  • When you introduce a list, say "these" not "the following". For example, "These are options for parameter X:" (note the colon) not "The following are options for parameter X."
  • 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" when it's unambiguous. (In Analytica documentation, "it" is rarely ambiguous.)
  • 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 short words instead of longer synonyms -- e.g. "use" not "utilize", "let" not "allow".
  • Use "parameter" not "argument" for the things listed in parentheses in a call to a function, or the definition of a function (where the attribute is called Parameters.)
  • Use long dash or double-dash around examples or interjections (rather than parentheses), as in "Use a reducing function -- e.g. Sum or Min -- rather than a transforming function."
  • You click a button or link (not click on). You press a menu to see the menu options. You select a menu option. You also select a node or text from a text field. You press (not hit or depress) a key or key combination on the keyboard.
  • Label web links so that users get a reasonable idea of what they will find on the linked page. There is no need to write "click this link" or "click here". By now, users know about clicking links. Better just to show hyperlinked text that labels where the link goes to, e.g. the name of the page or topic.

Analytica terminology

  • Capitalize terms used with a special meaning in Analytica -- such as, Variable, Object, Attribute, or Diagram -- to distinguish them from their common meaning, which is often similar but subtly different. There's no need to capitalize standard computer terms -- like, window, menu, button, mouse, keyboard -- or standard mathematical terms -- like, variable, function, parameter, array -- except when they're being used with a special Analytica take on the meaning, as for example, Variable.
  • Distinguish nodes, Variables and Objects. A node is the visual representation in a Diagram of a Variable or other class of Object. An Object can have multiple nodes -- e.g., the original node and aliases, including input and output nodes. A Variable is just one Class of object. For views or operations that apply to all Objects, use Object rather than Variable.
  • Use Edition of Analytica to mean Player, Professional, Enterprise, ADE, AWP, etc.. Use Release as in Release 4.2. Avoid version because it could mean either.
  • ADE and AWP are Editions of Analytica, just like Professional and Enterprise. So we don't need to say "Analytica and ADE" or "Analytica and AWP" as we have done often in the past. Optimizer is also an Edition, not an extension or option.  64-bit, however, is an extension or option that can be applied to selected Editions.

Lists

  • Use a bulleted lists, like this, wherever appropriate to show a list of items.
  • Use a numbered or lettered list only where the items are intrinsically ordered, as in a series of steps that would not work in a different order -- e.g.:
  1. Do this
  2. Now do this
  3. Finish up by doing this
  • Order items in a list (or sections in chapter) starting with the most commonly used or easiest first to most complicated or obscure. Hence,
    • when scanning through a list, readers will find what they want sooner on average, and
    • when reading through a list, readers will see the easy stuff first, and after learning that will better 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 a long list, organize items hierarchically by grouping related items together under subheads.

Typographic Conventions and FrameMaker Character Code Tags

Analytica Tutorial, User Guide, Optimizer Guide, and ADE documentation use Framemaker. In FrameMaker carefully adhere to the character tags specified here. There are some character tags that currently apply these font attributes automatically. Even so, please use the proper character tag, so that, in the future, if we decide to change the look of parameters we can simply change the definition of the "parameter" character tag and not have it affect other items.


Type of Text Typography FrameMaker Character Tag
Special term where introduced and explained, with link to Glossary Bold Italic Bold Emphasis
Window title, menus, menu item, dialog box title, panel title, and button label Bold UI Object
Analytica global object identifier or title, including variable, function, or module, in a code fragment. Bold and Capitalized UI Object
Checkbox label and other input label, like the Edit Attributes setting for the Preferences dialog Italics UI Label
Key on keyboard Italics: "Press Enter"; control-e Emphasis
Function name Bold and Capitalized with trailing parens, "()": Argmax() Function
Formal parameter name bold lowercase or "camelCase" to distinguish words when necessary: x, start, stepSize Parameter
parameter qualifier Capitalized to distinguish from formal parameter names 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
Special Analytica term Capitalize when used with special Analytica meaning, but not when used in its normal sense. Default font
Document name Italics and Capitalized, e.g. User Guide Emphasis

Analytica code

These guidelines and conventions are designed to make code easier to read. Please follow in user docs, wiki, and in sample models and libraries.:

  • Capitalize first character of identifiers of objects and functions, such as Speed_of_light, C,  Sum(). You can also use CamelCase, such as SpeedOfLight, DetermTable (Ana 4.3 remembers CamelCase identifiers).
  • Use uppercase for key words and constructs, like IF...THEN.. ELSE, BEGIN END, FOR... DO...
  • Use lowercase for identifiers of parameters and local variables in a function Parameters and Definition.
  • For results of Analytica expressions, use right-arrow "→" to show result:
 10^5 → 100K
  • Use Suffix notation, unless there is a reason not to.
  • Spacing conventions in code and expressions:
    • Add a space around low-precedence operators +, -, =, <, <=, >=, >, <>
    • No space around high-precedence operators "*", "/", and "^".
    • A space after, but not before separators ",", ":" and ";"
    • No space before or after 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)
  • When specifying function parameters, use the same guidelines -- i.e.
    • No space after or before "(" and ")".
    • Space after but not before separators ",", ":" and ";"
    • Lowercase start for function parameters.
    • Capitalize qualifiers:
Function F(x: Number; i: Index; camelCaseX: Optional Text)

Not 

Function F( x : number; I:Index ; CamelCaseX : optional text)
  • Code examples should be indented using 4 blanks for each indent; use the "code' paragraph tag in FrameMaker that indents 1/4"
  • The Title of a user-defined Function should be identical to its identifier, with underscore "_" replacing spaces and other non-alphanumeric chars, plus required (not optional) formal parameters without qualifiers. That makes it easy to find and select Functions from a library -- e.g.
 Function Flatten_array
Title: Flatten_array(x, i, j, k)
Parameters (x: [i, j]; i, j, k: Index)
  • Indent multiline Definitions -- four spaces per indent.

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. Don't include optional parameters unless they are usually used.

  • Function definition sections should use a Heading2 paragraph tag for the function title for the section.

In some cases, we include several related functions in one section. Then we should include them all in the same heading, e.g.

PDF(x) and CDF(x)

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 don't have otherwise meaningful names, to indicate what type is expected:

  • x, y, z: Numbers that may be scalar or array-valued.
  • 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
  • expr: An expression (not evaluated before calling function)
  • obj: Identifier of an Object (any Class)
  • attrib: Identifier of Attribute

Most named parameters in the User Guide 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 one 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.

In this wiki, each section describing a function 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.

Guidelines for Analytica wiki

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

Every new or modified function shd be annotated one of:

  • (Added in 4.2)
  • (Modified in 4.2)

Over time we should remove all annotations relating to earlier releases.

Comments


You are not allowed to post comments.