Reference articles provide information-oriented descriptions of specific components or characteristics of your product. The purpose of a reference article is to concisely present information as a structured set of entries, with little to no procedural or instructional content.
A reference article works well when it:
- is consistent in structure, terminology, and tone.
- contains concise, descriptive information that is relevant to its overview
- avoids high-level usage-instructions or description for the product as a whole
Summarize what this reference article is about.
- Explain what all the entries defined on the page have in common.
The structure of reference articles varies based on what kind of information you are documenting. Formats that permit structured presentation of entries are best: tables, lists, interactive object-schemas, etc. In most cases, reference information is easiest to express as a table.
Use the "don't repeat yourself" (DRY) method and re-use content if it's written for the same audience, and it fits within your reference document without modification.
Reference documentation can often be auto-generated from source code and/or comments within the code. It is typically easier to keep auto-generated docs current, accurate and complete, as the documentation is maintained next to the code it describes. Ensure code-generated documentation is thoroughly written. This is important for API reference docs and package descriptions documented in code doc-blocks or produced with tools such as the Open API tool chain.
-
Example 1.
-
Example 2.