Okapi Framework - Developer's Guide

Help Authoring Guidelines

When writing the help documents that go along with a module of the framework, you should try to adhere to the following guidelines to allow a more consistent user experience:

Formatting

Use the common CSS stylesheet help.css file located at the top of the help directory structure. Use a relative path to point to it.

Use <cite> for any text referring to a text of the user interface.
Example: The Custom sub-folder option.

Use <i> for resource property names.
Example: The approved target property.

Use <kbd> for key names.
Example: The shortcut is Ctrl+O.

Use <code> for any text referring to a source code, paths, and filenames
Example: Use <code> for any text referring to a source code.

Use <b> for emphasis. Be careful not to emphasize too many words.
Example: This is important.

Use relative path for links whenever possible.

Use slashes ('/') not backslashes ('\') in the links.

Terminology

Whenever possible use the terminology already in used in the other parts of the framework's documents. This avoid misunderstandings and help in getting a better view of the big picture.

Many terms are defined in the Glossary section of this guide. Use them.

Spelling

Use the US English spelling.