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 Analytica wiki often contain partially overlapping information about each function (and other features). Usually, the User Guide has a clearer introductory description and often better examples for common cases, and is better edited, but the wiki page 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 sources into a single page that it is easy to read, retains all key information, and avoids duplication.

Usually, each function has (or should have) its own wiki page. In a few cases, two or more closely related functions may share a page. When moving description of each function from the User Guide, you should copy it into the existing wiki page for that function, rather than creating a new page (or leaving it in a section of a parent page). You may find it easiest to copy the new material into the top of the existing wiki page, since the User Guide description is usually a better introduction, followed by clearer simple examples. Often you can use the new introduction to replace the existing introduction to the function. But, you will need to review the material carefully to make sure that the introduction in the wiki doesn't contain something important that isn't in the material from the User Guide.

The Standard Function Template

Each function page in the wiki should have a fairly standard format, including these elements:

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  The page title should always be the name of the function, without parameters -- e.g. Uniform, not "Uniform(a, b)". It is important to capitalize the function name -- i.e. first letter uppercase and remaining letters lowercase -- because Mediawiki links are case sensitive.

== Function call with main parameters ==:  i.e. Uniform(min, max) (when in doubt, just use 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.

Library: Function descriptions in the User Guide usually contain this section with the name of the library containing this function. This section is obsolete because the information is replaced by the Categories mechanism on the wiki (see below). After making sure the library is mentioned in the Categories, please delete this section (or just don't copy it from the User Guide).

Additional parameters and usage

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

History An optional section mentioning the Analytica release in which a new feature was introduced or modified. Many existing wiki pages have notations at the top or elsewhere saying things like “New to Analytica 4.3”. Please move such notations into this History section, since this information is of limited interest to most users. For release before 4.2 or so, it's fine just to delete these notations.

See also: A list of links to pages with related functions and concepts. It's a good idea to include this even if it's currently empty. Please add links to any functions or concepts that are obviously related. Completing this will require an Analytica expert.

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 -- e.g. 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