Documentation Style Guide

Adding links within the wiki

To preserve links when the documentation is upgraded / copied, use CRMDOC namespace, not the CRMDOC[XX] namespace, which redirects to the current version

e.g. http://wiki.civicrm.org/confluence/display/CRMDOC/Documentation+Maintainers

rather than

e.g. http://wiki.civicrm.org/confluence/display/CRMDOC32/Documentation+Maintainers

Documentation Style and Formatting Conventions

CiviCRM online documentation should follow these general formatting and language conventions as much as possible:

Formatting Conventions

CiviCRM labels - Field labels, clickable links or drop-down list choices that appear on CiviCRM screens are in BOLD, i.e., Click on New Contact.

Internal Links - Mentions of functions covered within the documentation are linked to that topic, i.e., Use.

External Links - Mentions of resources located outside the documentation wiki are linked to that topic and have a green arrow at the end, i.e., Yahoo!

Messages - Informational, error or warning messages are separated from the text using the "quote" function, i.e.:

Warning: You are about to delete important information...

Menus - Provide the complete list of drop down menu text items leading to the click on a menu selection in a single instruction with the » character prepended to the text for each level, e.g.:
»Administer »Manage »Access Control

Fields - most fields requiring input are in bold with a dash and an explanation, like this line.

Boxed Messages - Messages are assigned certain colors of boxes depending on their content:

Yellow messages are important information or steps necessary to perform before proceeding

Blue messages are purely informational

Green messages most often include helpful tips

Red messages are sparsely used for warnings around crucial functions

CAPS - Words in ALL CAPS are used for emphasis, i.e., "File MUST contain contact name"

Language

Use plain english, short words and short sentences.

Avoid jargon and explain any technical terms being used.

Commands are an efficient way to give instructions:
- "The user should then click the »New Event link."
- "Click the »New Event link."

Terminology

Home Page - The CiviCRM home page, the one you see when you first open CiviCRM.

Main Page - The main page of any section of CiviCRM, i.e., Main Global Settings page, etc.

dropdown - used for any menu that drops down with additional choices, aka pull-down menus.