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 elements of a function description

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

Page title:  The page title should always be the name of the function, without parameters -- e.g. Uniform, not "Uniform(a, b)". It is critical to capitalize the function name -- i.e. first letter uppercase and remaining letters lowercase. Mediawiki links are case sensitive, so it is important to use this convention consistently.

Function call with main parameters: E.g.  Uniform(min, max). Many functions have a long string of optional parameters. This subhead should include only the first few, most commonly used parameters, omitting the later more obscure optional parameters. When in doubt, just use what is in the User Guide.

Introduction: The next section, usually a paragraph is a brief description of what the function does, including a mention of its most common parameters. You can usually use the introduction from the User Guide, unless the introduction in the wiki is obviously better. You don't actually need a subheading Introduction. This text appears directly under the function call with main parameters.

'Examples: Show one or two examples of most common usages. 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).

Optional parameters: A list of the optional parameters, each on a separate line, followed by a phrase or paragraph explaining what each parameter is or does. It may also include example code and results using each parameter.

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.

Categories: Categories is a Mediawiki mechanism that lets you specify one or more categories containing this function (or other feature). Mediawiki then creates Category pages with links to all the pages in that category. It also shows links to the Category page(s) from each page in that category. Most existing function pages in the wiki already contain a Categories section. As explained above, most function descriptions in the User Guide have a Library section specifying what library contains the function. This section should be replaced by putting the library name in the Categories list -- e.g.. if the User Guide description contains Library: Array functions replace that by

 [[Category:Array functions]]

The categories are listed at the bottom of the displayed page regardless of where the wiki code is in the source page.

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