Reference Document Template

Tags: documentor reference

Reference material is information-oriented. Regarding software, reference guides describe the software - APIs, classes, functions, etc. In the context of the Open edX® Docs, reference docs are often in the form of informational lists (e.g., Resources for Students) and tables (e.g., Course Access Roles and Privileges).

Reference material is like a map. A map tells you what you need to know about the territory without having to go out and check it for yourself; a reference guide serves the same purpose for the product and its internal machinery. For example, this part works as the introduction to the article and as a description of the product of what this document is about.

The purpose of this document is to be as straightforward as possible. In addition to an accurate and precise description of the product you’re referencing, use examples of the uses and functions of the product to make it more comprehensive. For example, list details or a product glossary that the reader could need to use.

Example Lists

As mentioned, a reference document can contain lists detailing different elements, like a glossary or a list of resources to consult. Those lists could have different formats depending on their purpose. For example,

Ordered Lists

1. Reference A

2. Reference B

3. Reference C

Or

Unordered Lists

• Reference A

• Reference B

• Reference C

Table Example

Another vital resource you can use to create a reference document is a table. For example:

Example #	01
Title	Table Example
Last-Modified	MM-DD-YYYY
Documents	Document 1 Document 2 Document 3

Reference Links

In this type of document, links are usually added to refer to other sources that may interest the reader, such as GitHub repositories or documents from this same repository.

External Links

You can use inline links or indirect links. Indirect links are useful if you want to link to the same thing multiple times, or if the URL is really long and you want the raw RST to read more cleanly.

Internal Links

Warning

Usage of :doc: is an antipattern. It is fragile and prone to breaking cross references when docs are moved or renamed.

Adding in .. _reference: syntax to files and headings means cross-references can instead be made with the :ref: directive, which will be more robust to docs refactorings.

Link to Quick Reference: Writing RST and Markdown to reference a doc, or a place within a doc.

By default, it will use the title of the doc as the link text but you can override that with other text if you want.

See also

Review the Open edX Documentation Writing Style Guide to learn more about directives and other resources for creating your documentation.

RST Template

     Reference material is information-oriented. Regarding software, reference guides describe the software - APIs, classes, functions, etc. In the context of the Open edX® Docs, reference docs are often in the form of informational lists (e.g., Resources for Students) and tables (e.g., Course Access Roles and Privileges).

     Reference material is like a map. A map tells you what you need to know about the territory without having to go out and check it for yourself; a reference guide serves the same purpose for the product and its internal machinery. For example, this part works as the introduction to the article and as a description of the product of what this document is about.
     The purpose of this document is to be as straightforward as possible. In addition to an accurate and precise description of the product you’re referencing, use examples of the uses and functions of the product to make it more comprehensive.
     For example, list details or a product glossary that the reader could need to use.

     Example Lists
     =============

     As mentioned, a reference document can contain lists detailing different elements, like a glossary or a list of resources to consult. Those lists could have different formats depending on their purpose. For example,

     **Ordered Lists**

     #. Reference A

     #. Reference B

     #. Reference C

     Or

     **Unordered Lists**

     - Reference A
     - Reference B
     - Reference C


     Table Example
     =============

     Another vital resource you can use to create a reference document is a table. For example:

     +------------------+--------------------------------------------------------------+
     | Example #        | 01                                                           |
     +------------------+--------------------------------------------------------------+
     | Title            | Table Example                                                |
     +------------------+--------------------------------------------------------------+
     | Last-Modified    | MM-DD-YYYY                                                   |
     +------------------+--------------------------------------------------------------+
     | Documents        | - Document 1                                                 |
     |                  | - Document 2                                                 |
     |                  | - Document 3                                                 |
     +------------------+--------------------------------------------------------------+

     Reference Links
     ===============
     In this type of document, links are usually added to refer to other sources that may interest the reader, such as GitHub repositories or documents from this same repository.

     External Links
     --------------

     You can use `inline links <https://docs.openedx.org/en/latest/documentors/references/quick_reference.html#linking>`_ or `indirect links`_. Indirect links are useful if you want to link to the same thing multiple times, or if the URL is really long and you want the raw RST to read more cleanly.

     .. _Indirect links: https://docs.openedx.org/en/latest/documentors/references/quick_reference.html#linking

     Internal Links
     --------------

.. warning::

   Usage of ``:doc:`` is an antipattern. It is fragile and prone to breaking cross references when docs are moved or renamed.

   Adding in ``.. _reference:`` syntax to files and headings means cross-references can instead be made with the ``:ref:`` directive, which will be more robust to docs refactorings.


     Link to :ref:`Documentation Syntax Reference` to reference a doc, or a place within a doc.

     By default, it will use the title of the doc as the link text but you can override that with :ref:`other text <Documentation Syntax Reference>` if you want.

     ..  seealso:: Review the :ref:`Open edX Documentation Writing Style Guide` to learn more about directives and other resources for creating your documentation.

See also

About Open edX® Documentation Standards (concept)

Concept Document Template (reference)

Quickstart Document Template (reference)

How-To Document Template (reference)

Maintenance chart

Review Date	Working Group Reviewer	Release	Test situation

---

Feedback