Reference guide

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.

Introduction

A reference article provides users with descriptions of specific components or characteristics of your application. It aims to present concise, structured information that a user can quickly scan. It is important to limit procedural or instructional content.

Reference articles are often confused with API references. Though these documents help the users get acquainted with the application, they differ significantly in the type of target audience and content. The following table describes the differences:

	Reference	API Reference
Target Audience	Users who are unfamiliar with the problem space and product, and users seeking clarification on CLI commands and arguments.	Domain experts who know the problem space and wish to interact with the product using the product's API.
Content	Brief descriptions of referenced content, CLI commands and arguments.	Detailed information about available endpoints and the available parameters of an API.

Why do I need a reference article?

A reference article is important because it provides a structured and concise source of information that mirrors your application’s structure. Users can quickly and easily access it to find specific information about a product.

There are several common scenarios where reference topics are appropriate:

• For programming languages, a reference article should cover specific functions, methods, classes, and libraries, explaining syntax, parameters, return values, and providing examples.

• For technical specifications of hardware or software products, reference documents often provide detailed information on specifications, configurations, and compatibility. These references help users understand the technical capabilities of a product.

• For software applications, configuration settings refer to individual settings or options. Providing these settings in a reference document can significantly improve a user's ability to understand the purpose and possible values of each setting.

It is important to note that reference articles are often integrated with other content types, such as task topics, to create comprehensive documentation. For example, a task topic may provide step by step instructions for using a feature, with reference links to detailed parameters or endpoints at the bottom of the task for users who need more information.

Best practices for writing a reference article

When writing a reference it is important to:

• Ensure consistency in structure, terminology, and tone.
• Avoid high-level usage instructions or descriptions for the application.
• Provide concepts with essential vocabulary and context for users to learn and understand their tasks.
• Ensure that reference information is task-oriented and avoids unnecessary details.
• Always consider the user’s needs when crafting reference information.
• Ensure that the information supports users in making decisions or completing tasks related to the application’s functionality.
• Remove irrelevant information from documentation, as it can frustrate and confuse users.

About the “Reference description” section

Use this section to provide the following:

• Ensure that the section concisely summarizes the reference article's content and purpose.
• Keep the descriptions brief yet informative, offering users a clear understanding of the reference material.
• Avoid unnecessary details that could confuse or overwhelm readers. Instead, focus on highlighting key themes or functionalities covered in the article.
• Strive to strike a balance between brevity and completeness, ensuring that the summary effectively communicates the essence of the reference material.

About the “Table name or other structured entry” section

Use this section to provide the following:

• Include tables, lists, object schemas (attributes, objects), or other structured formats in this section.
• Use these formats to present information in an organized and easily understandable manner.
• Ensure that the structured entries provide comprehensive details on the topic at hand.
• Use active voice to make the descriptions clear and concise, enhancing readability.
• Aim for clarity and completeness in the presentation of information, while avoiding unnecessary complexity.
• Use tables and bulleted lists to increase readability and comprehension for users.

About the “Commands” section

Use this optional section to provide the following:

• Use this section to include code or code blocks, along with brief descriptions.
• If necessary, specify optional or required configurations for the commands.
• Provide examples demonstrating how the command operates with different configurations.

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