A reference document describes specific terms and phrases used by a product. It is information oriented and explains them with a few short sentences.
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.
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.
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.
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.
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.
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.
If you are using foreign terms that might be derived from e.g. Latin, French, Spanish or other “foreign” languages, add a brief explanation.
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.
Reference docs or specific reference manuals are typically used in more technically-oriented products.
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
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.
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.
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.