.. _Report a problem with the docs:

Report a problem with the docs
#################################

.. tags:: documentor, how-to

This how-to will help you create a GitHub issue related to the Open edX documentation.

.. contents:: Contents
  :local:
  :depth: 1

Prerequisites
*************

* You have a GitHub Account

  * If not `sign up here`_.

.. _sign up here: https://github.com/signup

Creating an Issue from GitHub 
*****************************

#. Log in to your GitHub account and go under the repository `docs.openedx.org <https://docs.openedx.org/>`_.

#. On the Navigation Bar, click on **Issues**.

   .. image:: /_images/documentors_howto/navigation_bar_github.png
      :width: 500px
      :align: center
      :alt: This image shows the GitHub navigation bar and the Issues option.

#. On the left side of the page, click on **New Issue**.

   .. image:: /_images/documentors_howto/new_issue_buttton.png
      :width: 500px
      :align: center
      :alt: This image shows the New Issue Button.

#. You will see a menu from which you can create an issue from scratch or use one of the templates already defined by the community. Regarding documentation, the recommendation is to use the template **Report Issue With Existing File (for docs writers)**.

   .. image:: /_images/documentors_howto/issue_template.png
      :width: 500px
      :align: center
      :alt: This image shows the Issues Templates menu.

#. Fill in all mandatory fields: "Issue Title", “Filename” and “What is broken about this file?”. A detailed description of the issue is highly recommended to enhance understanding of the requirements. Here, you can also assign the issue to a particular user, but it is preferable to wait for a volunteer.

#. Click the button **Create** to upload the issue.

   .. image:: /_images/documentors_howto/issue_template_form.png
      :width: 500px
      :align: center
      :alt: This image shows the Documentation Issue Template Form.

Creating an Issue from a Document
**********************************

This guide outlines the process for creating an issue to report a problem, suggest an improvement, or request updates in the Open edX documentation repository while you are consulting a particular document.

#. When viewing a document on `docs.openedx.org`_, scroll to the top of the page.

#. Click the GitHub icon at the right corner of the page.

#. A menu will scroll down, and you will see three options. Click on **Open an Issue**.

   .. image:: /_images/documentors_howto/open_issue_repository.png
      :width: 500px
      :align: center
      :alt: This image shows the Open an Issue Option in the Options menu of the Open edX documentation.

#. Fill in all mandatory fields: "Issue Title", “Filename” and “What is broken about this file?”. A detailed description of the issue is highly recommended to enhance understanding of the requirements. Here, you can also assign the issue to a particular user, but it is preferable to wait for a volunteer.

#. Click the button **Create** to upload the issue.

   .. image:: /_images/documentors_howto/issue_template_form.png
      :width: 500px
      :align: center
      :alt: This image shows the Documentation Issue Template Form.

.. seealso::

   :ref:`About Open edX Documentation Standards` (concept)

   :ref:`Documentor Guidelines` (reference)

   :ref:`Documentation Maintenance Process` (reference)

   :ref:`Guidelines for Writing Global English` (reference)

   :ref:`Open edX Documentation Writing Style Guide` (reference)

   :ref:`Documentation Templates` (reference)
   
   :ref:`Documentation Syntax Reference` (reference)

   :ref:`Documentation Audiences` (concept)

   :ref:`Update An Existing Doc via GitHub` (how-to)

   :ref:`Add New Documentation via GitHub` (how-to)


**Maintenance chart**

+--------------+-------------------------------+----------------+--------------------------------+
| Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
+--------------+-------------------------------+----------------+--------------------------------+
|              |                               |                |                                |
+--------------+-------------------------------+----------------+--------------------------------+