These guidelines should help you write Analytica documentation that is clear and consistent. The main goal is to avoid unnecessary words and convoluted grammar. Much of it is standard stuff for writers and editors, but some is specific for Analytica documentation. The guidelines apply to this Analytica wiki, to User Guides (currently distributed as PDFs), as well as help text and error messages within Analytica.
Feel free to edit any wiki pages to make them follow this guide more closely.
Write "Avoid the passive voice" not "The passive voice should always be avoided
Write: "Analytica displays an error message" Not: "An error message is displayed."
Write: "You can use Function F to ... " Not: "Function F may be utilized to ..."
Use imperative voice ("Do this") when explaining to user how to do something (as in this document). Also use imperative for a series of steps, for example:
Select Graph setup from Result menu
Check Stacked option
Click OK
Write: "Select Graph setup from the Result menu" Not: "The user should select select Graph setup from the Result menu".
And Definitely not: "The Graph setup should be selected from the Result menu". Yuck!!
Use present not future tense for what Analytica does:
Write: "When you click OK, it closes the dialog." Not: "When you click OK, Analytica will close the dialog."
When you introduce a list, say "these" with a colon, not "the following".
Write "These are options for parameter X:" (note the colon) Not"The following are options for parameter X."
You, we, it, and Analytica
Refer to the reader or user as "you", and the writer(s) or Lumina as "we".
Write: "We invite you to email us your comments" Not: "The reader is invited to email Lumina their comments.".
If the recipient would otherwise be ambiguous, write "Please email Lumina your comments." where "your" refers to the reader.
It's fine to refer to Analytica as "it" (she doesn't mind):
Write: "When you click the button, it displays the dialog box." Not: "When the user clicks the button, Analytica will display the dialog box".
Definitely not: "When the button is clicked, the dialog box is displayed"
Mention "Analytica" by name only if "it" is ambiguous. (In Analytica documentation, "it" is rarely ambiguous.)
Common words and concepts
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 (the action is to press and hold)
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". People know about clicking links! The browser shows hyperlinked text in blue to show that it's a clickable link.
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.
Don't use node to mean a Variable or Object. 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 classes of Object, use Object rather than Variable. But, do use node when you are actually referring to creating, finding, moving, or deleting a node (including input or output field) in a Diagram.
Use Edition of Analytica to mean Player, Professional, Enterprise, ADE, ACP, etc..
Use Release as in Release 4.2.
Avoid version because it could mean either Edition or Release.
ADE and ACP are Editions of Analytica, just like Professional and Enterprise. So we don't need to say "Analytica and ADE" or "Analytica and ACP" as we have done often in the past. Optimizer is also an Edition, not an extension or option.
Titles
Page titles
use Sentence case, with the last word in singular, e.g. (User-defined attribute) to enable fast interlinking and readability of the wiki markup, such as
[[User-defined attribute]]s are suitable for creating attributes that do not exist. To create a new [[user-defined attribute]], proceed as follows.
Do NOT use all capitals in plural (e.g. User-Defined Attributes) because it adds visual clutter without adding new information, slows down wiki-linking and makes wiki markup harder to read and edit:
[[User-Defined Attributes|User-defined attributes]] are suitable for creating attributes that do not exist. To create a new [[User-Defined Attributes|user-defined attribute]], proceed as follows.
Titles of Analytica components, such as names of windows, functions etc
use the exact name and capitalization used in the software so that the users will not be confused by different terms.
There is no need to rename all existing pages, but use the suggested style for new pages or when merging multiple pages of similar content.
To make wiki markup easier to read and edit, do NOT use full urls in internal links, i.e. in links to other pages on the Analytica wiki: [[http://wiki.analytica.com/index.php?title=User-defined attribute|User-defined attribute]].
TOC
The preferred method is to have the Table of Contents as the first item on the page, preceding any introductory sections. This is so because a concise, structured Table of Contents gives a faster and easier-to-read overview of the page contents than a textual overview.
A Table of Contents is created automatically in MediaWiki if there are more than three sections on the page but can be forced by __TOC__ command (placed at the top of the page).
Lists
Use a bulleted list, 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.:
Do this
Now do this
Finish up by doing this
Order items in a list (or sections in chapter) starting with the easiest to understand or most commonly used first and progressing to the most complicated or obscure at the end. This way, readers scanning down a list, will,
find what they want sooner on average, and
read the easy stuff first, and so will better understand the harder stuff that comes later.
Alphabetic ordering adds little: If you already know the name of the function (or whatever), which you need for alphabetic search, it's faster to use electronic search -- or use the index in a printed version.
No list should be longer than 7 to 10 items. Organize longer lists hierarchically by grouping related items into sublists.
Tables
Indent tables by one tab (precede by one colon (:)):
These guidelines and conventions are designed to make code easier to read. Please follow in user docs, wiki, and in sample models and libraries.:
Indent code lines by one tab (precede by one colon (:)).
Using colons is preferred to the method of indenting by space-keys because spaces are hard to notice and count in wiki markup, the code is easier to read on the more contrasting white background than on the gray background displayed with using spaces, and the true-type font is sufficient for distinguishing code from the surrounding text.
Capitalize the first character of the identifier of all variables and other objects, such as Speed_of_light, C, Sum(). You can also use CamelCase, such as SpeedOfLight, DetermTable.
Use all uppercase for key words and constructs, like IF...THEN.. ELSE, BEGIN END, FOR... DO... VAR, METAVAR etc.
Use lowercase for identifiers of function parameters and local variables in Parameter Definition, upper case for indexes parameters, for example
Function Quadrate(x, y, I, J)
For results of Analytica expressions, use right-arrow "→" to mean "the preceding expression generates the following result":
10^5 → 100K
Use Suffix notation for numbers, unless there is a reason not to. It's clear, compact, and Analytica's default.
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. Uppercase for index parameters.
Capitalize qualifiers:
Function F(x: Number; I: Index; camelCaseX: Optional Text)
Not
Function F( x : number; i:Index ; CamelCaseX : optional text)
Indent multiline expressions (Definitions) with four spaces per indent -- default provided by Analytica when you enter tab character.
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, J)
Parameters (x: [i, J]; I, J, K: Index)
Do not insert wiki links to code, link function names in the surrounding text or under the See Also section.
Other typographic conventions
As we move the Analytica Tutorial, User Guide, Optimizer Guide, and ADE User Guide to the Analytica Wiki, we need to retain consistency of typographic conventions. In Framemaker, each of these is a character style (see tag in right column). Unfortunately, the wiki doesn't offer such special styles, so we adopt these conventions:
Type of Text
Typography
Example
Wiki Code
FrameMaker Character Tag
Special Analytica term
Capitalize and link when used with special Analytica meaning, but not when used in its normal sense.
Formal parameter name -- i.e. the declared name of a function parameter distinct from the actual parameter, which is the value or expression passed in a call to a function
Use lowercase or "camelCase"; surround by by double angled brackets «a», except when inside formal parameter declaration (within parens after function name). Italicize optional parameters when inside parentheses. Code (courier) font so I appears distinct from the number 1.
You cannot evaluate a call to RunConsoleProcess directly from an input variable.
This can be done by
1) using colons (:) in front of every row for indentation and <code> tags around every row::<code>''You cannot evaluate a call to RunConsoleProcess directly from an input variable.''</code>
2) using <pre>tags around text (preferred method with multi-line error messages):
You cannot evaluate a call to RunConsoleProcess directly from an input variable.
Document name
Italics and Capitalized
User Guide
''User Guide''
Emphasis
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.
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
History: Summarizes when a new feature was introduced or modified. Move all links like "New in Release 4.1" to the History section (or just delete them)
Enhancement requests
Documentation requests
Categories
The category indexes are a big benefit of MediaWiki. You can specify one or more Categories for each page. The page then automatically appears in the corresponding Category page. For example, for a page on MdArrayToTable contains the code
If you want to categorize two or more items with different categories, on the same page, create a redirect page for each item with the item's name. Include a category markup in the redirect page. This might look like this:
[[Category:Database Functions]]
#REDIRECT [[Functions To Read Excel Worksheets#SpreadsheetCell]]
Put the category tag(s) before the redirect or it won't work right. When linking to an item that lives on a page with other items, link to the redirect page, i.e., use
[[SpreadsheetCell]]
, not
[[Functions To Read Excel Worksheets#SpreadsheetCell]]
.
If the heading within the page you redirect to has extra stuff in the heading, for example:
All of these links except the most recent (currently Release 4.6) should be moved to the History section at the end of each page, to minimize ancient "What's new" links of little interest to 99% of readers.
