ContactsLaw Documentation:Style Guide

Contributions to this wiki should follow this style guide.

How To Use This Wiki

This wiki is implemented using MediaWiki, which is the same software that powers Wikipedia.

For general help with MediaWiki, refer to MediaWiki Help.

Key topics include:

Write in a professional tone
Be verbose, elaborate if what you're explaining:
- Has exceptions or caveats
- Could be misinterpreted
- Doesn't tell the full story
Avoid slang, lingo and casual language
Inform, don't dictate
Focus on how the software is designed and behaves, avoid step-by-step instructions (except in separate articles)
ContactsLaw is a software ecosystem. If you are writing content that is specific to one particular view of the system (e.g. Desktop App) then communicate this clearly to readers.

Note: MediaWiki uses the headings to automatically build the Table of Contents for each article.

Key terms (e.g. contact, document, matter) are not proper nouns
Be consistent (when in doubt, use the same terms that appear to end users in the software)
Avoid ambiguity (e.g. the term "field" could refer to many different concepts, while "text field" or "custom field" are more specific)
Avoid region-or-jurisdiction-specific terms (e.g. "sales tax" vs "GST", "conveyancing" vs "settlements")

Use bold formatting to introduce the main topic of the article (and other key terms)
Use italic formatting for the names of user-interface elements, notes and remarks
Use monospace formatting for code, expressions and other syntax
Less is more, don't over-decorate
NEVER USE ALL CAPS
Always start from the lowest heading level and do not skip levels when using sub-headings
Avoid using other colours for text
When using bullets/numbering, do not end list items with semicolons or the word "or" (as is prevalent in legal documents)
Replace "smart" quotes (66s and 99s) with straight quotes (11s)

Create internal links to other articles wherever they are known to exist (and update your articles to include them once they do exist)
You can create links to articles that do not exist yet (to flag the need to create such an article)
Do not over-link, only decorate the first occurrence (or first per heading if appropriate)
Override the link text if you need to use the plural form of a word (e.g. Contact|contacts) or other variations
Link text should match the casing of the sentence in which the link appears (e.g. "You can search Contact|contacts by name" vs "You can search Contact|Contacts by name")
Do not use link text that is completely different to the article name (e.g. Matter|file)
Do not place links in headings

Place articles in categories. Most articles should belong to at least one category. Avoid categories that will only ever contain one article.
If you create new categories, be sure to create the article for the category itself (otherwise, readers will not be able to see the list of articles).
Use hatnotes to link to articles that elaborate further on topics you cover briefly, e.g.
Format abbreviations (e.g. ATO) to let readers know what they stand for (when introducing them for the first time).

Wikipedia Manual of Style - For any topics not covered here, you should refer to Wikipedia's style guide.