Difference between revisions of "Analytica Docs guidelines"
m |
|||
| (10 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
| + | [[Category: Documentation guidelines]] | ||
| + | |||
Guidelines and conventions for wording and formatting this Analytica wiki. | Guidelines and conventions for wording and formatting this Analytica wiki. | ||
| Line 11: | Line 13: | ||
* 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 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. | * 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 <nowiki>[[Analytica | + | * Media wiki is case sensitive for page links. So <nowiki>[[Analytica Docs guidelines]]</nowiki> links to this page, but <nowiki>[[Analytica docs Guidelines]]</nowiki> doesn't. |
* Use spelled-out phrase and use redirect for acronyms and abbreviations. | * Use spelled-out phrase and use redirect for acronyms and abbreviations. | ||
* Keep page titles brief: E.g. "Modules" rather than "How to use modules" | * Keep page titles brief: E.g. "Modules" rather than "How to use modules" | ||
| Line 18: | Line 20: | ||
→ full details at Wikipedia:Naming conventions | → full details at Wikipedia:Naming conventions | ||
| − | == | + | == Headings == |
| − | The main title of each page (including this) is a level 1 heading, in dark | + | 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. | Other headings should be level 2 or lower, e.g. | ||
| Line 29: | Line 31: | ||
* 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. | * 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 | + | * Currently, many Analytica Docs pages include level 1 headings within the page. They should be demoted to level 2 or lower. |
== Contents == | == Contents == | ||
| − | Mediawiki automatically generates a Contents section for each page from the subheadings. | + | 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 == | == Capitalization == | ||
| − | * Analytica function names, classes and system words | + | These words should be capitalized: |
| + | * Analytica function names, classes and system words -- e.g. Sum, Variable, Index, Samplesize. | ||
| − | * Key Analytica concepts | + | * Key Analytica concepts -- e.g. Intelligent Arrays, Lazy evaluation, Flow Architecture |
| − | * Key user interface elements | + | * Key user interface elements -- e.g. Diagram, Uncertainty view, Toolbar. |
| − | == Analytica == | + | == 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 <blockquote>Unlike most computer languages, Analytica requires you to name each Index (dimension) when subscripting, but doesn't care about the sequence of dimensions. </blockquote> | |
== Deleting Pages == | == 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: | |
<nowiki>#REDIRECT [[New page name]]</nowiki> | <nowiki>#REDIRECT [[New page name]]</nowiki> | ||
| + | |||
| + | === Language style === | ||
| + | See and follow the [[Document style guide]] for guidelines on writing style, including avoiding passive voice, typographic styles, and special Analytica terminology. | ||
Latest revision as of 00:37, 17 January 2023
Guidelines and conventions for wording and formatting this Analytica wiki.
Reference resources
Details on wiki markup formats [1]
Wiki markup quick reference card [2]
![[2]](https://meta.wikimedia.org/wiki/Help:Reference_card#/media/File:MediaWikiRefCard.png){kind=link}
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
Enable comment auto-refresher