Document style guide

We (Max and colleagues) wrote these guidelines to help you write docs that are clear and easy to read. The Analytica tutorial, user guides, like any software docs are a core part of the product. They are critical to making the software easy to learn and use. We intend Analytica -- and therefore its docs -- to be clear and accurate. These guidelines apply to the Analytica wiki, as well as help text and error messages within Analytica. They also apply to emails, proposals, reports and other writing for Lumina prospects and customers, and user guides for Analytica applications.

Much of it is standard stuff for technical writers and editors that we've borrowed and adapted from standard style manuals. The main goal is to make the language easy to read and understand -- in part by avoiding unecessary words and convoluted grammar. Some is specific for Analytica docs, especially some of the terminology.

Feel free to edit any wiki pages to make them follow this guide more closely.

For style guidelines for Analytica models see Analytica model style guide.

Language

Use imperative, active voice, and present tense

Use the imperative when explaining or suggestion what to do (as we do here), because it concise and direct -- for example:

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

Imperative is especially suitable for a series of steps, you (the "user") should perform. Number the steps when you must perform them in that sequence:

1. Select Graph setup... from the Result menu
2. Check Stacked option
3. Click OK

Technically, an imperative sentence is a form of "active voice", where "you" (the reader or software user) is the implied subject. Somtimes it is helpful to make the subject explicit -- for example:

• You should avoid the passive voice.
• not: The passive voice should always be avoided

• When you press ctrl+F, it opens the Find dialog.
• 'Not: When the user presses ctrl+F, the Find dialog is displayed.

Use present not future tense for what Analytica does:

• When you press ctrl+F, it opens the Find dialog.
• Not: When you press ctrl+F, it will display the Find dialog.
• Better: Press ctrl+F to open the Find dialog.

You, we, it, and Analytica

As you saw above, we use "you" to refer to the reader or software user, and "we" or "us" to refer to the writer or Lumina:

• You can use Function F to ...,
• Not: Function F may be utilized to ...
• 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 for example:

• Email Lumina your comments.

When the subject isn't "you", it's often "Analytica". Since this documentation is about Analytica, it's fine to refer to Analytica as "it" (she doesn't mind):

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

It's occasionally useful to mention "Analytica" explicitly to emphasize a special Analytica way of doing things to contrast it to other languages and software:

• Analytica uses name-based subscripting, instead of position-based subscripting common in most computer languages.

It's, don't and common contractions

It's fine to use common contractions like "it's", "don't", "isn't" and so on. They're a bit faster to read, and convey a kind of informality, which is good. We try to avoid academic, government, or corporate-speak.

Click, Press, Select

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

• Don't write "click this link" or "click here". People know about clicking links! The browser shows hyperlinked text in blue or underlined (or something) to show that it's clickable.

Common words and concepts

Use short words instead of longer synonyms:

• "use" is better than "utilize"
• "let" is better than "allow".
• Use "parameter" not "argument" for the things listed in parentheses in a call to a function (the actual parameters), or the definition of a function (the formal parameters). The Attribute is called Parameters.

• Use long dash (m-dash) or double-dash around examples or interjections (rather than parentheses) -- for example "Use a reducing function -- e.g. Sum or Min -- rather than a transforming function."

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 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 a node in a Diagram that you select, create, find, drag, or deletee (including a input or output node).

• Use Edition of Analytica to mean Player, Professional, Enterprise, ADE, ACP, and so on.
• Use Release as in Release 5.3.
• 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.

Lists

• Use a bulleted list, like this, wherever appropriate.

• Use a numbered or lettered list only where the items are intrinsically ordered -- e.g. a series of steps that won't work in a different order:

1. Do this
2. Next, do this
3. Finish up by doing this

Introduce a list, whether bullets or numbered steps, with a colon:

• These are options for parameter X: (note the colon)
• Not: The following are options for parameter X.

• There's no need to introduce a list by saying "the following". A simple colon followed by a list makes it clear without the extra words.

• If each item is a single phrase, there's no need for a period or comma at the end. But, do use a period if there are multiple sentences, as in this list.

• Order items in a list (or sections in a chapter, or parameters of a function when designing a function) from the easiest or most commonly used to the most complicated and esoteric. That way, readers scanning down the list will:
  • find what they want sooner on average,
  • read the easy stuff first, preparing them to understand the harder stuff that comes later, if needed.
• Alphabetic ordering is usually pointless online: If you already know the name of the function (or whatever), which you would need for alphabetic search, you can use Find ctrl+F.

• Avoid making lists with more than about 5 items at the same level. If you have a lot more items, grouping related items into sublists as a hierarchy. Again, that makes it easier to scan a list to find what you want.

Media wiki conventions

Page Titles

In this wiki, use Sentence case for page titles. The first word starts with a capital letter. Other words should not unless they are proper nouns (including Function names):

• Document style guide
• Not: Document Style Guide

It's important to be consistent with this because Mediawiki (which powers this wiki) is case-sensitive for internal links.

Use singular nouns, not plural:

• User-defined attribute
• Not: User-defined Attributes

You can add plurals for internal links by added "s" or other letters after an internal link:

[[User-defined attribute]]s are suitable for creating attributes that do not exist. To create a new [[user-defined attribute]], proceed as follows.

There's no need to rename all existing pages, but please use the suggested style for new pages or when merging multiple pages of similar content.

To make wiki markup easier to read and edit, use the standard wiki links to other wiki pages, like:

User-defined attribute</nowiki>

not full urls in internal links, like:

[http://wiki.analytica.com/index.php?title=User-defined attribute|User-defined attribute]

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.

Table of Contents

Mediawiki automatically inserts a Table of Contents if the page has more than 3 headings, before the first heading. You can force its insertion with __TOC__ at the top of the page).

It's good to include a brief sentence or two introducing the topic of each page before the first heading (and so before the TOC). That way a reader can quickly see if this topic is what they want before reading the TOC, which may be long.

Tables

Use wikitable format to create a table: Precede it by a colon (:)) to indent the table:

:{| class=wikitable
! 
! Column 1
! Column 2
|-
! Row 1
| Cell 11
| Cell 12
|- 
! Row 2
| Cell 21
| Cell 22
|}

The code above yields this table:

	Column 1	Column 2
Row 1	Cell 11	Cell 12
Row 2	Cell 21	Cell 22

See Guide to Converting Documents to MediaWiki for more.

Images

Use the wiki Upload file functionality to upload image files.

Indent images by one tab (precede by one colon (:)), as in:

:[[image:ImageFile.png]]

The wiki syntax for images with centered captions on white background is as follows.

One image:

:{|border=0
|bgcolor=white|[[image:ImageFile.png|frame|<center>Image caption.</center>]]
|}

Two images side-by-side:

:{| border="0"
|bgcolor=white|[[image:ImageFileOne.png|frame|<center>Image caption one</center>]]
|bgcolor=white|[[image:ImageFileTwo.png|frame|<center>Image caption two</center>]]
|}

or

:{|
|bgcolor=white|[[File:ImageFileOne.png|thumb|500px|<center>Image caption one</center>]]
|bgcolor=white|[[File:ImageFileTwo.png|thumb|500px|<center>Image caption two</center>]]
|}

For sample images created this way, see Kernel Density Smoothing and Node Alignment, Sizing, and Spacing.

Formulas

Indent mathematical formulas by one tab (precede by one colon (:)) and surround by <math> tags, e.g.

:<math>
E=mc^2
</math>

which results in

[math]\displaystyle{ E=mc^2 }[/math]

For help with mathematical formulas, see the Wikipedia help page.

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.	Intelligent Arrays, Attributes	[[Intelligent Arrays]]	Default font
Window title, menus, menu item, dialog box title, panel title, and button label	Bold	File, Attribute Panel	'''File'''	UI Object
Analytica global object identifier or title, including variable or module	Bold	for example variable X, X	'''X'''	UI Object
Checkbox label and other input label	Italics	Edit Attributes setting for the Preferences dialog	''Edit Attributes''	UI Label
Key on keyboard	Italics	"Press Enter"; control+e	Press ''Enter''	Emphasis
Function name	Linked (which bolds functions when on their own page) with trailing parens, "()". No links needed when embedded in code.	Sequence()	[[Sequence]]()	Function
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.	Sort(a, I, keyIndex ); «a», «I», «keyIndex»	«a»How does one find these characters? - Install English (United States) International keyboard - for « use AltGr (Right-Alt) + [ - for » use AltGr (Right-Alt) + ]	Parameter
parameter qualifier	Capitalize to distinguish from formal parameter names	Bool, Text, Number	Bool	Parameter
Code and script examples, expressions and variable definitions	Fixed width font, indented rows	MDTable(T,Rows,Cols,[Car_type,Mpg],'average','n/a')	This can be done by 1) using colons (for indentation) and code tags: :<code>MDTable(T, Rows, Cols, [Car_type, Mpg], 'average', 'n/a')</code> 2) using colons and <tt> tags: :<tt>MDTable(T, Rows, Cols, [Car_type, Mpg], 'average', 'n/a')</tt> 3) putting a space at the beginning of the line (the code will be displayed in a gray box):  MDTable(T, Rows, Cols, [Car_type, Mpg], 'average', 'n/a') 4) surrounding the code by <pre> tags (preferred method with multi-line code): <pre style="background:white; border:white; margin-left: 1em;"> MDTable(T, Rows, Cols, [Car_type, Mpg], 'average', 'n/a')	Code
Error message examples	Fixed width font in italics, indented rows	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): <pre style="background:white; border:white; margin-left: 1em; font-style:italic"> 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. We should then include them all in the same heading, e.g.

PDF(x) and CDF(x)

Conventions: Use the recommended name for each qualifier rather than its deprecated synonyms. Omit "Atom" which is of more interest to the implementer than the user of a 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.
• expr: An expression, which is not evaluated before calling function
• obj or o: A handle to an an Object (of any Class)
• attrib: The identifier of an 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 these sections (where appropriate):

• 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)
• Requirements: Expectations or constraints on parameters.
• If there are many parameters, list them as a bulleted list, explaining each one
• More complex examples
• 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", such as Tutorial, User Guide, Optimizer Guide, ADE User Guide, 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)

• Common subheads:
  • Examples
  • Syntax
  • Tips
  • See also
  • History: Summarizes when a new feature was introduced or modified. Move all old links like "New in Release 5.1" when we're up to Release 5.3 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

Category:Array Flattening Functions

No matter where you locate this code, it shows this at the bottom of the page:

Category: Array Flattening Functions

And it inserts MdArrayToTable in the page Category:Array Flattening Functions This makes it easy for readers to find all the array-flattening functions.

You can list multiple categories:

 Category: Array Flattening Functions, Category: Array Functions, Category: Table functions

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:

===SpreadsheetCell(wb, sheet, col, row)===

Make a simple anchor tag using a div tag such as

===<div id="SpreadsheetCell">SpreadsheetCell(wb, sheet, col, row)</div>===

This way you can use just "#SpreadsheetCell" in the redirect URL.

History

• Many features have links from and to a "What's new" page for the release in which they were first introduced or modified, e.g. What's new in Analytica 5.0?.
• Ideally, links to a "What's new" page should only exist for the most recent release -- e.g. What's new in Analytica 5.4?. Ancient history is of little interest to 99% of readers.
• So, when working on a page, please move information about when a feature was introduced or modified for older releases to the History section at the end of each page.

See Also

Every page should have a See Also section, with links to pages on related topics that someone reading this page may find useful. In this case:

• Analytica model style guide for Analytica code and model documentation
• Guide to Converting Documents to MediaWiki