diff --git a/source/_images/documentors_howto/image_example.png b/source/_images/documentors_howto/image_example.png new file mode 100644 index 000000000..aa69bff1a Binary files /dev/null and b/source/_images/documentors_howto/image_example.png differ diff --git a/source/_images/documentors_howto/xblock_example.png b/source/_images/documentors_howto/xblock_example.png new file mode 100644 index 000000000..421695175 Binary files /dev/null and b/source/_images/documentors_howto/xblock_example.png differ diff --git a/source/documentors/index.rst b/source/documentors/index.rst index e0cfe1060..e5c0079f0 100644 --- a/source/documentors/index.rst +++ b/source/documentors/index.rst @@ -55,6 +55,7 @@ Open edX Documentors * :doc:`references/doc_guidelines` * :doc:`references/quick_reference_rst` + * :doc:`references/templates/index` * :doc:`references/doc_templates` * :doc:`references/doc_checklist` +++ diff --git a/source/documentors/references/doc_templates.rst b/source/documentors/references/doc_templates.rst index 136408137..3f9e963cb 100644 --- a/source/documentors/references/doc_templates.rst +++ b/source/documentors/references/doc_templates.rst @@ -1,311 +1,10 @@ Documentation Templates ####################### -This page contains templates that you can copy directly and use to develop new topics. - -To copy RST code examples from this topic, just hover over the codeblock to see the copy button, and copy the RST as needed. - -.. contents:: Contents - :local: - :depth: 1 - - - -Topic Titles -************ - -Open edX Documentation uses hierarchical titles, indicated by the special characters underneath each title. - -Copy the following titles as needed. - -.. include:: ../references/rst_samples/headings.txt - -.. note:: - :class: dropdown - - It is a rule of RST that the line of underline characters must be as long as or longer than the title; if the line is shorter than the title, the documentation will not build. - -Content Links at the top of a Topic -*********************************** - -If you have a long topic with several Heading 2s, you can use the **contents** directive at the top of the topic to provide links to the different sections (as shown at the top of this topic). - - -Copy the contents directive as needed. - -.. code-block:: RST - - Topic Title - ########### - - An introductory sentence for the topic, followed by the contents directive, which will create the links to subsections. - - .. contents:: Contents - :local: - :depth: 1 - - First Heading 2 - *************** - - -Develop Sections -**************** - -You can nest sections in the topic as needed, to give it structure and break it up into discrete parts. - -Copy the Topic and Section Structure as needed - -.. code-block:: RST - - Topic Title - ########### - - Introduce the topic - - If this is a long topic with multiple sections, use the **contents** directive below: - - .. contents:: Contents - :local: - - Section 1 - ********* - - Introduce Section One - - Subsection 1 - ++++++++++++ - - Content for Section 1/Subsection 1 - - Subsection 2 - ++++++++++++ - - Content for Section 1/Subsection 2 - - Section 2 - ********* - - Introduce Section Two - - Subsection 1 - ++++++++++++ - - Content for Section 2/Subsection 1 - - Subsection 2 - ++++++++++++ - - Content for Section 2/Subsection 2 - -Create a How-to -*************** - -Copy this codeblock to start a new how-to topic. - -.. code-block:: RST - - How-to Title - ############ - - .. Titles should be imperative. https://www.grammarly.com/blog/imperative-sentences/ - - .. How-tos should have a short introduction sentence that captures the user's goal and introduces the steps. - - This how-to will help you accomplish task X. - - Assumptions - *********** - - .. This section should contain a bulleted list of assumptions you have of the - person who is following the How-to. The assumptions may link to other - how-tos if possible. - - * You know how to use Git - - * You know how to create an empty course. - - Steps - ***** - - .. A task should have 3 - 7 steps. Tasks with more should be broken down into digestible chunks. - - #. Step 1. - - #. Step 2. - - #. Step 3. - - .. Following the steps, you should add the result and any follow-up tasks needed. - - .. seealso:: - - # To cross-reference a label use :ref: - :ref:`reference to link to` - - # To point to another document in the docs.openedx.org filetree, use :doc: - :doc:`/relative/path/to_the_document` - - -Add an Ordered List -******************* - -Copy this codeblock to start an ordered (numbered) list. - -.. include:: ../references/rst_samples/ordered_lists.txt - -Add an Unordered List -********************* - -Copy this codeblock to start an unordered (bulleted) list. - -.. include:: ../references/rst_samples/unordered_lists.txt - -Nested Lists -************ - -You can nest arbitrarily, using the **#** symbol for ordered lists and **\*** for unordered lists. - - -.. include:: ../references/rst_samples/nested_lists.txt - - -Create a Reference -****************** - -Copy this codeblock to start a new reference topic. - -.. code-block:: RST - - Reference Title - ############### - - The reference title should just name the object or subject. Such as *Course Section* or *Course Dates*. - - Provide a high-level overview of topic. - - What is it? - *********** - - Provide a high-level view of what you are documenting - what it is and why one would care. - - Complex topics may contain 2 or more subsections. - - What is ? - +++++++++++++++++++++++++++ - - When you need to break down a subject, you can break it down into subsections (H3s). Typically you would have 0 H3s, or 2+ H3s. - - What is ? - +++++++++++++++++++++++++++ - - When you need to break down a subject, you can break it down into subsections (H3s) - - Aspects of the Subject - ********************** - - Create sections for different aspects of the subject; for example, for problem types, you would have a section on all the settings and a section on the XML representation of the problem. - -Add a Substitution -****************** - -In RST, a *substitution* serves as a variable which you can set a value for once, then use repeatedly. This is useful for words or phrases that are used often, as it enables you to edit the value once and change it everywhere. - -You also need to use substitutions for inline images, as explained below. - -Substitutions are all kept in the source/substitutions.txt file in the documentation project on GitHub. - -Copy the format for the substitution as needed. - -.. code-block:: RST - - .. |variable name| replace:: value - - .. |Platform name| replace:: Open edX - -You then add the *variable name* inline in the topic. - -.. code-block:: RST - - A line of text with an |variable name| inserted. - - -Add a Sidebar -************* - -You can add any content in a sidebar. Open edX uses sidebars for image thumbnails, videos, and other notes. - -The sidebar must come directly after a heading. - -Copy this codeblock to add a new sidebar topic. - -.. code-block:: RST - - .. sidebar:: Sample Sidebar - - Any content, typically an image, video, or note. - -Add an Image to a Topic -*********************** - -You can add an on its own separate line, inline, or in a sidebar. - -You can also add an image directly, or add a thumbnail of an larger image, which when clicked on will open the full image. - -You must save images in the ``source/_images`` directory before adding a reference to it in a topic. - -Add an Image on its Own Line -============================ - -Copy this codeblock to an image on its own line. - -.. code-block:: RST - - Line of content, followed by a line with an image. - - .. image:: /_images/image-file-name - - Or, a line of content, followed by a clickable thumbnail of a large image. - - .. thumbnail:: /_images/image-file-name - -Add an Image Inline -=================== - -To add an image inline, you must first create a substitution for the image in the substitutions.txt file. - -Copy the format for the substitution as needed. - -.. code-block:: RST - - .. |variable name| image:: /_images/image-file-name - -You then add the *variable name* inline in the topic. - -.. code-block:: RST - - A line of text with an |variable name| inserted. - -Add an Thumbnail in a Sidebar -============================= - -You can add a thumbnail in a sidebar, a common practice for How-to topics. - -The sidebar must come directly after a heading. - -Copy this codeblock to add a new sidebar with a thumbnail. - -.. code-block:: RST - - .. sidebar:: Sample Sidebar with a thumbnail - - .. thumbnail:: _images/image-file-name - -Use Inline Formatting -********************* - -RST supports **bold**, *italic*, and ``mono-spaced`` characters. You can also make GUI elements appear as :guilabel:`objects`. - -Copy this codeblock for inline formatting as needed. - -.. include:: ../references/rst_samples/inline.txt +.. toctree:: + :maxdepth: 2 + :glob: + Templates + + \ No newline at end of file diff --git a/source/documentors/references/index.rst b/source/documentors/references/index.rst index 143461484..9756862b3 100644 --- a/source/documentors/references/index.rst +++ b/source/documentors/references/index.rst @@ -6,3 +6,4 @@ Documentors: References :glob: * + templates/index.rst diff --git a/source/documentors/references/templates/doc_concept_template.rst b/source/documentors/references/templates/doc_concept_template.rst new file mode 100644 index 000000000..44e292458 --- /dev/null +++ b/source/documentors/references/templates/doc_concept_template.rst @@ -0,0 +1,70 @@ +Concept Document Template +######################### + +A concept is a document that clarifies and illuminates a particular topic. It is understanding-oriented. It could be considered a conceptual guide. This type of document answers a why question. It could be descriptive, historical, or even propose different alternatives to explain the bigger picture and give context. + +For example, “What is an XBlock? The Open edX platform provides different components, called XBlocks, that can work to create a course, like text, video, assessment, and discussions”. + +Since this type of document seeks to explain a topic, you will likely need to add images to illustrate the topic you are talking about. For example: + + +.. image:: /_images/documentors_howto/xblock_example.png + :width: 500px + :align: center + :alt: This image shows the Advance Module List, where the XBlocks are added to the platform. + +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. + +.. _Indirect links: https://docs.openedx.org/en/latest/documentors/references/quick_reference_rst.html#linking + +Internal Links +-------------- + +Link to :doc:`doc_how_to_template` in the same folder or :doc:`../quick_reference_rst` in a different +folder. + +By default, it will use the title of the doc as the link text but you can override that with :doc:`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 +************ + +.. code-block:: RST + + Concept Document Template + ######################### + + A concept is a document that clarifies and illuminates a particular topic. It is understanding-oriented. It could be considered a conceptual guide. This type of document answers a why question. It could be descriptive, historical, or even propose different alternatives to explain the bigger picture and give context. + + For example, “What is an XBlock? The Open edX platform provides different components, called XBlocks, that can work to create a course, like text, video, assessment, and discussions.” + + Since this type of document seeks to explain a topic, you will likely need to add images to exemplify the topic you are talking about. For example: + + + .. image:: /_images/documentors_howto/xblock_example.png + :width: 500px + :align: center + :alt: This image shows the Advance Module List, where the XBlocks are added to the platform. + + 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. + + .. _Indirect links: https://docs.openedx.org/en/latest/documentors/references/quick_reference_rst.html#linking + + Internal Links + -------------- + + Link to :doc:`doc_how_to_template` in the same folder or :doc:`../quick_reference_rst` in a different + folder. + + By default, it will use the title of the doc as the link text but you can override that with :doc:`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. + + diff --git a/source/documentors/references/templates/doc_how_to_template.rst b/source/documentors/references/templates/doc_how_to_template.rst new file mode 100644 index 000000000..4c6462ac9 --- /dev/null +++ b/source/documentors/references/templates/doc_how_to_template.rst @@ -0,0 +1,87 @@ +How-To Document Template +######################## + +A How-To guide document guides the reader through the steps to solve a real-world problem. This documentation is goal-oriented and similar to recipes, with directions that guide the reader through the steps to achieve a specific end. + +For example, following the steps in this How-To guide, you can create a how-to document for any repository for the Open edX platform. + +.. START HERE + +1. Copy this document into a new file to edit as needed. At the bottom, you will find a template in RST to make this process easier. + +2. Edit the title according to the topic you are working on. Adding the how-to is unnecessary, but the matter should be clear from this point on. + +3. Edit the description with relevant information to introduce the reader to the topic and the problem you will teach them how to solve. + +4. Start creating the step-by-step the reader should follow to solve the problem. Please don't ignore any step, even if it is evident. + +5. Add the images and audiovisual resources you think could be necessary to clarify the process. Remember that the callouts should be in Open edX red ``(#d23228)`` and round-edged rectangles. Also, save images as .png or .jpg files for upload. For example: + +.. image:: /_images/documentors_howto/image_example.png + :width: 500px + :align: center + :alt: This image example shows how to access the GitHub repository from the Open edX documentation repository. + +6. If the solution requires code, add the reference the person should use. For example, the following case is an HTML code. + +.. code-block:: HTML + +

Title

+ +.. seealso:: To learn more about how to add a code block, visit the `Code blocks documentation `_. + +7. Add any reference that could be important for someone to understand the topic. For example, here is additional information about `how to style for Read the Docs `_. + +Now, you have a how-to document. Congratulations! + +.. END HERE + +.. note:: To upload your document to RTD, you can review the `Documentors Quickstarts `_. + +.. see also:: Review the Style Guide to learn more about directives and other resources to create your documentation. + +RST Template +************ + +.. code-block:: RST + + How-To Document Template + ######################## + + A How-To guide document guides the reader through the steps to solve a real-world problem. This documentation is goal-oriented and similar to recipes, with directions that guide the reader through the steps to achieve a specific end. + + For example, following the steps in this How-To guide, you can create a how-to document for any repository for the Open edX platform. + + 1. Copy this document into a new file to edit as needed. At the bottom, you will find a template in RST to make this process easier. + + 2. Edit the title according to the topic you are working on. Adding the how-to is unnecessary, but the matter should be clear from this point on. + + 3. Edit the description with relevant information to introduce the reader to the topic and the problem you will teach them how to solve. + + 4. Start creating the step-by-step the reader should follow to solve the problem. Please don't ignore any step, even if it is evident. + + 5. Add the images and audiovisual resources you think could be necessary to clarify the process. Remember that the callouts should be in Open edX red ``(#d23228)`` and round-edged rectangles. Also, save images as .png or .jpg files for upload. For example: + + .. image:: /_image/documentors_howto/image_example.png + :width: 500px + :align: center + :alt: This image example shows how to access the GitHub repository from the Open edX documentation repository. + + 6. If the solution requires code, add the reference the person should use. For example, the following case is an HTML code. + + .. code-block:: HTML + +

Title

+ + + .. seealso:: To learn more about how to add a code block, visit the `Code blocks documentation `_. + + 7. Add any reference that could be important for someone to understand the topic. For example, here is additional information about `how to style for Read the Docs `_. + + Now, you have a how-to document. Congratulations! + + .. note:: To upload your document to RTD, you can review the `Documentors Quickstarts `_. + + .. see also:: Review the Open edX Documentation Writing Style Guide to learn more about directives and other resources for creating your documentation. + + diff --git a/source/documentors/references/templates/doc_quickstart_template.rst b/source/documentors/references/templates/doc_quickstart_template.rst new file mode 100644 index 000000000..7c32816b4 --- /dev/null +++ b/source/documentors/references/templates/doc_quickstart_template.rst @@ -0,0 +1,238 @@ +Quickstart Document Template +############################ + +What Is a Quickstart +******************** +A quickstart is a brief, streamlined guide that helps users get up and running with a tool, project, or system as quickly as possible. Quickstarts focus on the essential steps to start working with a particular technology, often covering: + +#. **Setup Requirements** – Prerequisites like software dependencies or configuration steps. + +#. **Installation** – How to install the necessary files or dependencies. + +#. **Primary Usage** – Commands or actions to perform basic operations. + +#. **Testing and Verification** – Ways to ensure everything is working correctly. + +#. **Common Next Steps** – Information on where to go next, often with links to detailed documentation. + +A good quickstart is designed for users who want to dive in with minimal setup. For example, allowing developers to try out a tool or platform without wading through extensive documentation upfront, or empowering course authors to quickly get up and running with a complex area of Studio. + +For this Quickstart template, we will go through the process of creating this document, including how to add or embed one document in another and the principal tools to guide a learner. + +Because a Quickstart is usually composed of two or more How-tos and some concepts and references, it is essential to add a table of contents to guide the reader through the document. For example: + +1. `What Is a Quickstart`_ +2. `Prerequisites Example`_ +3. `How To Embed One Document in Another`_ +4. `How To Embed Only a Section`_ +5. `Useful Resources`_ + +Prerequisites Example +********************** + +- Outline required knowledge (e.g., familiarity with Open edX basics). +- List any tools or configurations needed (e.g., access to an Open edX instance, software, or plugins). + +How To Embed One Document in Another +************************************ + +A Quickstart may be the union of different documents, such as how-tos, references, and concepts. To avoid duplicate documents, you can embed one document into another using the ``include`` directive. This directive allows you to include the content of another file located in the same repository. Here's how you can do it: + +1. Copy the following code in the file to embed the other document. + +.. code-block:: RST + + .. include:: path/to/other_file.rst + +2. Replace the example path with the embedded document path. For example: + +.. code-block:: RST + + include:: ../templates/doc_how_to_template.rst + +How to Embed Only a Section +*************************** + +If you want to include or embed only certain sections of a document, you can follow these steps: + +1. Open the document you want to embed. Add ``.. START HERE`` at the beginning and ``.. END HERE`` at the end of the section you want to embed. + +2. You will embed the other document in the document. Use the following code to the exact place where you want to add that particular section. Do not forget to edit the document link that you want to include in your Quickstart. + +.. code-block:: RST + + + .. include:: docs/section1.rst + :start-after: .. START HERE + :end-before: .. END HERE + +The reader will see something like this: + +How-To Document Template Section +================================ + +.. include:: ../templates/doc_how_to_template.rst + :start-after: .. START HERE + :end-before: .. END HERE + +Useful Resources +**************** + +Here is a list of the most used resources to create a Quickstart: + +Images +======= + +Add the images and audiovisual resources you think could be necessary to clarify the process. Remember that the callouts should be in Open edX red ``(#d23228)`` and round-edged rectangles. + +.. code-block:: RST + + .. image:: /_images/documentors_howto/image_example.png + :width: 500px + :align: center + :alt: This image example shows how to access the GitHub repository from the Open edX documentation repository. + +.. image:: /_images/documentors_howto/image_example.png + :width: 500px + :align: center + :alt: This image example shows how to access the GitHub repository from the Open edX documentation repository. + +Links +====== + +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. + +.. _Indirect links: https://docs.openedx.org/en/latest/documentors/references/quick_reference_rst.html#linking + +Directives: +=========== + +Usually, for this type of document, you can use different directives like ``warning``, ``note``, and ``see also``, among others. + +.. see also:: Review the Open edX Documentation Writing Style Guide to learn more about directives and other resources for creating your documentation. + + +RST Template +************ + +.. code-block:: RST + + Quickstrat Document Template + ############################ + + What Is a Quickstart + ******************** + A quickstart is a brief, streamlined guide that helps users get up and running with a tool, project, or system as quickly as possible. Quickstarts focus on the essential steps to start working with a particular technology, often covering: + + #. **Setup Requirements** – Prerequisites like software dependencies or configuration steps. + + #. **Installation** – How to install the necessary files or dependencies. + + #. **Primary Usage** – Commands or actions to perform basic operations. + + #. **Testing and Verification** – Ways to ensure everything is working correctly. + + #. **Common Next Steps** – Information on where to go next, often with links to detailed documentation. + + A good quickstart is designed for users who want to dive in with minimal setup. It benefits developers, allowing them to try out a tool or platform without wading through extensive documentation upfront. + + For this Quickstart template, we will go through the process of creating this document, including how to add or embed one document in another and the principal tools to guide a learner. + + Because a Quickstart is usually composed of two or more How-tos and some concepts and references, it is essential to add a table of contents to guide the reader through the document. For example: + + 1. `What Is a Quickstart`_ + 2. `Prerequisites Example`_ + 3. `How To Embed One Document in Another`_ + 4. `How To Embed Only a Section`_ + 5. `Useful Resources`_ + + Prerequisites Example + ********************** + + - Outline required knowledge (e.g., familiarity with Open edX basics). + - List any tools or configurations needed (e.g., access to an Open edX instance, software, or plugins). + + How To Embed One Document in Another + ************************************ + + A Quickstart may be the union of different documents, such as how-tos, references, and concepts. To avoid duplicate documents, you can embed one document into another using the ``include`` directive. This directive allows you to include the content of another file located in the same repository. Here's how you can do it: + + 1. Copy the following code in the file to embed the other document. + + .. code-block:: RST + + .. include:: path/to/other_file.rst + + 2. Replace the example path with the embedded document path. For example: + + .. code-block:: RST + + include:: ../templates/doc_how_to_template.rst + + How to Embed Only a Section + *************************** + + If you want to include or embed only certain sections of a document, you can follow these steps: + + 1. Open the document you want to embed. Add ``.. START HERE`` at the beginning and ``.. END HERE`` at the end of the section you want to embed. + + 2. You will embed the other document in the document. Use the following code to the exact place where you want to add that particular section. Do not forget to edit the document link that you want to include in your Quickstart. + + .. code-block:: RST + + + .. include:: docs/section1.rst + :start-after: .. START HERE + :end-before: .. END HERE + + The reader will see something like this: + + How-To Document Template Section + -------------------------------- + + .. include:: ../templates/doc_how_to_template.rst + :start-after: .. START HERE + :end-before: .. END HERE + + Useful Resources + **************** + + Here is a list of the most used resources to create a Quickstart + + Images + ====== + + Add the images and audiovisual resources you think could be necessary to clarify the process. Remember that the callouts should be in Open edX red ``(#d23228)`` and round-edged rectangles. + + .. code-block:: RST + + .. image:: /_images/documentors_howto/image_example.png + :width: 500px + :align: center + :alt: This image example shows how to access the GitHub repository from the Open edX documentation repository. + + .. image:: /_images/documentors_howto/image_example.png + :width: 500px + :align: center + :alt: This image example shows how to access the GitHub repository from the Open edX documentation repository. + + Links: + ====== + + 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. + + .. _Indirect links: https://docs.openedx.org/en/latest/documentors/references/quick_reference_rst.html#linking + + Directives: + =========== + + Usually, for this type of document, you can use different directives like ``warning``, ``note``, and ``see also``, among others. + + .. see also:: Review the Open edX Documentation Writing Style Guide to learn more about directives and other resources for creating your documentation. + diff --git a/source/documentors/references/templates/doc_reference_template.rst b/source/documentors/references/templates/doc_reference_template.rst new file mode 100644 index 000000000..34aa997a4 --- /dev/null +++ b/source/documentors/references/templates/doc_reference_template.rst @@ -0,0 +1,141 @@ +Reference Document 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 `_ 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_rst.html#linking + +Internal Links +-------------- + +Link to :doc:`doc_how_to_template` in the same folder or :doc:`../quick_reference_rst` in a different +folder. + +By default, it will use the title of the doc as the link text but you can override that with :doc:`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 +************ + +.. code-block:: RST + + 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 `_ 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_rst.html#linking + + Internal Links + -------------- + + Link to :doc:`doc_how_to_template` in the same folder or :doc:`../quick_reference_rst` in a different folder. + + By default, it will use the title of the doc as the link text but you can override that with :doc:`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. + diff --git a/source/documentors/references/templates/index.rst b/source/documentors/references/templates/index.rst new file mode 100644 index 000000000..86ac7aa6f --- /dev/null +++ b/source/documentors/references/templates/index.rst @@ -0,0 +1,11 @@ +Open edX Document Templates +############################ + +.. toctree:: + :maxdepth: 1 + :glob: + + doc_concept_template + doc_reference_template + doc_how_to_template + doc_quickstart_template \ No newline at end of file