A reference document describes specific terms and phrases used by a product. It is information oriented and explains them with a few short sentences.
What is the definition of reference documentation?
The meaning of reference is typically a list of specific terms and their meaning, or can also describe a relationship between different terms and words. It can be understood as a dictionary or thesaurus – but specific for you software product or web application.
It is also used in scientific writing, to list citation from author, and the source of information, used publication and concepts.
In the area of technical writing it is used to describe and explain specific terms and words. So within the different documentation types, special terms can be linked directly to the explanation in the reference manual.
How to write a good reference entry
The reference entry should contain at least the term and the explanation. The definition should be in a similar, consistent wording. If useful, add links to related information. Adding rich resources as a picture, video or other elements might not be ideal, to keep the reference entry short and the reference list clear.
A reference article could use the following elements.
- Title: name of the reference term
- Description: explanation and definition (2-3 sentences)
- Remarks: (optional) if relevant for the term
- Concept / area: (optional) if multiple reference documents exist (e.g. for each module of your software / web application)
- Related documents: links to additional resources that relate to or use the specific term
What is a reference document?
A reference document consists of multiple reference entries. The goal of the reference list or reference sheet is to able to link to the definition for the whole documentation base. So they should be somehow linkable – e.g. having separate entries or documents for each term, or at least be able to link with hyperlinks and anchor #. Each entry should be formatted and structured in the same format.
Multiple reference articles can be listed in a reference map – e.g. by alphabetical order, or grouped by topic or module.
Also when searching inside the whole documentation for such a term, the reference document entry should be suggested prominently in the search result.
What elements should be listed in a reference guide?
Depending on the software product or application, the following areas and concepts might be added to the reference guide. The goal is to explain the concept or word with 2-3 sentences or less. Link explanation docs or other reference pages – if existing – in the documentation software or create a specific entry in the knowledge base.
Persona and user groups
If the persona or user group has a specific meaning or might not be clear, to the customer it is helpful to define each of the terms. So it is clear for everybody what a “admin” means in your software product. Also specific permission or restriction could be mentioned here.
Procedures and business processes
Shorty describe a specific procedure or process, that is used often inside the application. Link to specific explanation that describes the value in detail. Also features, activity, report, services or methods could be added.
Foreign words and meaning
If you are using foreign terms that might be derived from e.g. Latin, French, Spanish or other “foreign” languages, add a brief explanation.
Technical and scientific terms & concept
Typical terms that is clear for every developer but not for the customer, or might be misleading, should be explained and defined. For example a “class” or “object” has a different meaning outside of the developer’s world and a typical reader might not get the relationship to an object oriented programming language.
What are good examples of reference docs?
Reference docs or specific reference manuals are typically used in more technically-oriented products.
Microsoft Style Guide – Developer – Reference documentation
The article describes how to create reference articles that can be used by the developer or technical writer to create a reference documentation for a software product, from the developer perspective and to be consumed by a software engineer or software architect.
The elements of a reference entry are as following
- Title and description
- Declaration & syntax
- Parameters
- Return value
- Remarks
- Example
- Requirements or Applies to
- See also
- Further, optional elements: Property value, Exceptions/error codes, Permissions
URL: https://docs.microsoft.com/en-us/style-guide/developer-content/reference-documentation
Docker Reference documentation
The “Reference documentation” landing page of the Docker virtualization platform lists different concepts as “File formats”, “Command-line interfaces (CLIs)”, “Application programming interfaces (APIs)” and “Drivers and specifications”. Each section contains the specific terms with a 1 sentence description – and a link to the detailed [explanation] of the concept.
URL: https://docs.docker.com/reference/
Sanity.io Reference Docs
The docs of Sanity.io, a unified content platform, also contains a section titled “Reference docs”. It is described as “technical description of the various components that make up the Sanity platform”.
It lists the main elements as HTTP API, Schema Types, Client libraries and more, linking to a detail page with specific technical information how to access this service or API.
URL: https://www.sanity.io/docs/reference
Questions about reference document?
If you have a question or need some more information about the reference entries and docs, reach out to us. Subscribe to our newsletter to get more information and content about multilingual documentation.
This page is part of the comprehensive list of documentation types.
[Continue reading]