Analytica Docs guidelines


Guidelines and conventions for wording and formatting this Analytica wiki.

Reference resources

Details on wiki markup formats [1]

Wiki markup quick reference card [2]

Naming pages

  • The name of each page (or "article" as called in wikipedia) is the heading appearing at the top of the page as well as the link to the article.
  • The first character is automatically capitalized. Subsequent words should be all lowercase, except for proper names or acronyms.
  • Media wiki is case sensitive for page links. So [[Analytica Docs guidelines]] links to this page, but [[Analytica docs Guidelines]] doesn't.
  • Use spelled-out phrase and use redirect for acronyms and abbreviations.
  • Keep page titles brief: E.g. "Modules" rather than "How to use modules"
  • These characters are not allowed in page titles: # + < > [ ] | { } /.
  • The maximum length is 255 characters.

→ full details at Wikipedia:Naming conventions

Headings

The main title of each page (including this) is a level 1 heading, in dark teal color. Other headings should be level 2 or lower, e.g. 

 == Level 2 Section heading ==
 === Level 3 Subsection heading ===
  • Don't use a heading that redundantly repeats the main title (or something close to it) near the start of the page. Some existing pages do this, and should be changed.
  • Currently, many Analytica Docs pages include level 1 headings within the page. They should be demoted to level 2 or lower.

Contents

Mediawiki automatically generates a Contents section for each page from the headings and subheadings, if there are more than three headings. Put this contents section at the top of each page

Capitalization

These words should be capitalized:

  • Analytica function names, classes and system words -- e.g. Sum, Variable, Index, Samplesize.
  • Key Analytica concepts -- e.g. Intelligent Arrays, Lazy evaluation, Flow Architecture
  • Key user interface elements -- e.g. Diagram, Uncertainty view, Toolbar.

No need to mention Analytica

Almost all content in these Docs relates to Analytica. So, it's redundant to mention "Analytica" except when explicitly contrasting usage in Analytica to other modeling software or languages. Thus, a page should be titled "Syntax" not "Analytica syntax". But you could say

Unlike most computer languages, Analytica requires you to name each Index (dimension) when subscripting, but doesn't care about the sequence of dimensions.

Deleting Pages

Never delete any pages.  If a new page or page with a better title replaces an existing page, retain the old page, but add a Redirect so it does not break any links to the original page. You can add a redirect easily -- when Editing Source, make the page's first line: 

#REDIRECT [[New page name]]

Language style

See and follow the Document style guide for guidelines on writing style, including avoiding passive voice, typographic styles, and special Analytica terminology.

Comments


You are not allowed to post comments.