Quickstart Document Template

Quickstart Document Template#

Tags: documentor reference

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:

  1. Setup Requirements – Prerequisites like software dependencies or configuration steps.

  2. Installation – How to install the necessary files or dependencies.

  3. Primary Usage – Commands or actions to perform basic operations.

  4. Testing and Verification – Ways to ensure everything is working correctly.

  5. 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.

.. include:: path/to/other_file.rst

  1. Replace the example path with the embedded document path. For example:

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.

.. include:: docs/section1.rst
        :start-after: .. START HERE
        :end-before: .. END HERE

The reader will see something like this:

How-To Document Template Section#

  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:

This image example shows how to access the GitHub repository from the Open edX documentation repository.

  1. If the solution requires code, add the reference the person should use. For example, the following case is an HTML code.

<h1 class="title">Title</h1>

See also

To learn more about how to add a code block, visit the Code blocks documentation.

  1. 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!

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.

.. 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.
This image example shows how to access the GitHub repository from the Open edX documentation repository.

Directives:#

Usually, for this type of document, you can use different directives like warning, note, and see also, among others.

RST Template#

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 <https://docs.openedx.org/en/latest/documentors/references/quick_reference_rst.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_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.

See also

About Open edX® Documentation Standards (concept)

Concept Document Template (reference)

Reference Document Template (reference)

How-To Document Template (reference)

Maintenance chart

Review Date

Working Group Reviewer

Release

Test situation
Contents