How to combine function descriptions

This provides guidelines for moving the Analytica Tutorial, User Guide, and Optimizer from Framemaker (or PDF) into the Analytica wiki in Mediawiki format.

Guide for integrating Function descriptions

The user guide and wiki often contain partially overlapping information about each function. Usually, the User Guide has a clearer introductory description, sometimes better examples for the common cases, but the wiki has more details and reference material, especially on recently added or more obscure parameters and features. The trick is to integrate the information from the two so that it is easy to read, retains all key information, but avoids duplication.

The Standard Function Template

Categories: Most functions should already have categories listed. One that needs to be added is the Library, which will become a category (i.e. for a function with Library: Array functions → [[Category:Array Library]] (these will be listed at the bottom regardless of where the wiki code is)

Page title:  Function call without parameters, i.e. Uniform

== Function call with main parameters ==:  i.e. Uniform(min, max) (when in doubt, just take what is in the User Guide)

Introduction: Returns a distribution or sample of values distributed uniformly between min and max. 

== Examples ==: of most common usage. Include a result table and/or graph where needed.

Additional parameters and usage

== Optional Parameters ==: Talks about how to use optional parameters and contains any examples if needed.

== History ==: Optional section mention the Analytica release in which new features were introduced. This will only be used if within the Wiki page there are existing “New to Analytica 4.x” headings.

==See also==: An important section. Should list related functions and concepts.

How to document a function

1. Make sure the page title is correct -- the page title should be the function call, but with no parameters, i.e. Uniform.
2. Check the function in Analytica (i.e. simply create a new node and type in the name of the function in the definition. ExpressionAssist should pop up with function) to make sure that the page is using the correct parameter names
3. Create the main section with the Function call with main parameters. If there is a discrepancy between the Wiki and the User Guide the heading, i.e. Uniform(min, max) should contain the same parameters listed in the Wiki. Be sure to check the parameter names with the software.
   • Make sure declaration uses standard format, parameters lowercase, no space after “(“ or before “)” but a space after each “,”).
4. In the main section, there should be a short introduction. Often the intro paragraph from the User Guide is best. The intro should describe the most common use and behavior of the function. Supplement with any important points from the Wiki intro. If the Wiki text has significantly more information than the User Guide, the Wiki text should be used instead. Additional optional and more rarely used parameters should be described later (after initial examples).
5. Next is the Examples section, which should contain common cases -- i.e., no examples using optional parameters. Often the User Guide has better examples so these should be put in first. Results tables should be styled as seen here or in the Example Table later in this page.
   • Code should be at the top of the table. Columns should be spaced at 75px or so. Indexes should be bolded. Text should be aligned left.
6. Next is the Optional Parameters section, which would have information on different parameters and special features. Each optional parameter should be in its own subsection, with the heading as the name of the optional parameter. Like in the introduction, there may be some overlapping material for this section. Typically the User Guide content is more well-written, but if the Wiki has additional information it should also be included.
7. If there are any sections or headings preceded with “New to Analytica 4.x” or similar text,this text should be removed. Instead, a new section at the bottom but before ==See More== should be added listing these new features by version.
8. If there is a Library section then it should be removed and the library should be added as a category, i.e. ==Library== Array → [[Category:Array Library]].
9. See Also section -- existing section should be fine and typically does not need to be altered. In general it should contain:
   • Link(s) to the parent category page — e.g. Functions that create Indexes
   • Link(s) to related functions
   • Link(s) to sample models that use this function

Example Table

Here is an example table formatting. Code should be at the top of the table. Columns should be spaced at 75px or so. Indexes should be bolded. Text should be aligned left. MDTable(T,Rows,Cols,[Car_type,Mpg],'average','n/a') →

	Mpg ▶
Car_type ▼	26	30	35
VW	2185	1705	n/a
Honda	2330	n/a	2210
BMW	n/a	2955	2835

Conventions

• Subheads: The wiki often has “subheads” at same level as main page heading. They should all be one or more levels lower,e.g.
  • == Subheading ==
  • === Subsubheading ===
• Parameters: Should match the software (which is not necessarily the same as the User Guide). Should always be lowercase, even when one letter. While the Use Guide often bolds parameters, the Wiki should use double angle brackets for «parameters» when referred to outside of the function. When referred to with a function, i.e. Sequence(start, end, step), then parameters should be in parentheses with spaces after each comma. In code when parameters are called by name (i.e. descending: True), there should be a space after the colon.
• Functions: should be linked to like so [[Sequence]] except in headings and in code. When using parenthesis to denote parameters, there should not be a space between the function and the parentheses, i.e. Sequence(start, end, step).
• Null should be linked: [[Null]]
• Special Analytica Terms linked: [[Intelligent Array]], [[Attribute]]
• Parameter Qualifier: should just be capitalized (i.e. Boolean, Array)
• Variables: should be Bold and Capitalized; the User Guide identifies Analytica variables using fixed width, e.g. Destinations where the wiki often uses italic e.g. Destinations.

Example Pages

Function pages that have already been combined and cleaned. Page numbers are PDF page numbers, not document page numbers

• Sequence - p 184 in User Guide
• Sort - p 210 in User Guide
• Sum - p203 in User Guide
• Uniform - p 276 and 284 in User Guide