Documentation Style Guide
Documentation Style Guide
The purpose of this section is to provide form and substance recommendations for editors of CDM documentation. "Documentation" in this context means any form of written guidance to CDM users and includes:
- the CDM user documentation
- release notes provided with each CDM release
- any description developed in the logical model itself, which
includes:
- data types and attributes
- enumerations
- functions and rules
- test descriptions
- any other areas of the logical model where a textual description may be provided
The intended audience for the CDM documentation includes software developers, data modelers, legal experts, business experts, and other subject matter experts who may have expertise in one area related to financial products, but are not experts in every area.
The baseline for the recommendation is standards for spelling, punctuation, and other style rules applicable to British English. The recommendation in this document extends this rule set with a set of guidelines applicable to documentation for logical models. The recommendation does not provide an exhaustive list of all of the standard British English rules, but provides selective examples that are common to documentation in general.
Writing and editing style is subjective and a matter of personal preferences, rather than right or wrong. The following guidelines are intended to ensure that the documentation provides consistent styling, regardless of who writes it, but should not be interpreted as an authoritative source on "good" styling.
Unless otherwise noted, the recommended rules apply to all forms of CDM documentation. When rules are applicable only to certain forms of documentation (for instance, the logical model descriptions or the release notes), they will be specified as such.