The reference article

Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our templates GitLab repository.

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

Content of your reference article

The Overview section

Summarize what this reference article is about.

• Explain what all the entries defined on the page have in common.

The Body section

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.

Code-generated documentation

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.

Reference article examples

• Example 1.

• Example 2.

---

Explore other templates from The Good Docs Project. Use our feedback form to give feedback on this template.