Establish and Document the Application's Reference Documentation

This chapter explains how to establish and document the reference material readers consult for facts about an Application.

Definition

Reference Documentation is business and technical reference material that readers consult for facts about an Application rather than for procedures, such as business rules, data dictionaries, Application Programming Interface (API) references, configuration references, and the standards the Application follows.

Why Reference Documentation Matters

Procedures tell people what to do; Reference Documentation tells them what is true. When a business user disputes a calculation, when an analyst needs to understand a field, or when an engineer needs to know what a configuration setting does, they need reliable Reference Documentation. Without it, people answer such questions by reading code or asking experts, which is slow and depends on availability.

Establish the Reference Documentation

Identify the reference material the Application’s users, support teams, and engineers need, typically including:

• Business rules and calculations the Application implements.

• Data dictionaries describing the Application’s key data elements.

• API references for its Published APIs.

• Configuration references explaining each significant setting.

• The standards, policies, and regulations the Application is designed to follow.

• Glossaries of Application-specific terms.

Generate reference material from authoritative sources, such as API definitions and configuration schemas, wherever possible, so that it stays accurate.

Document and Share the Reference Documentation

Publish the Reference Documentation in the Business and Reference section of the Application Documentation, or link to it where it is generated in the Application’s repositories. Update it with every Release that changes the facts it describes.

Best Practice: Establish and Document the Application’s Reference Documentation

It is a best practice to both establish and document the solution for answering factual questions about an Application: identify and publish the business rules, data dictionaries, API and configuration references, standards, and glossaries readers need, generated from authoritative sources wherever possible.

Benefits: Reliable Reference Documentation lets users, analysts, and engineers answer factual questions themselves, quickly and correctly, instead of reading code or waiting for an expert. Generating it from authoritative sources keeps it accurate as the Application changes.

Connections to Related IF4IT Practices and Inventories

The Data and Information Inventory and Attributes describes how data and information types are recorded, which complements an Application’s data dictionaries.