Documentation Style Guide

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...

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."

• Use active verbs whenever possible.
  • "After the link is clicked by the user..."
  • "After you click the 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.