FC-0068: How to document of how to create an issue (#803)

* FC-0068: How to document of how to create an issue This PR creates a How-to document to create issues for the Open edX documentation. This process aligns with the documentation maintenance project. * Update create_github_issue.rst * Update source/documentors/how-tos/create_github_issue.rst Co-authored-by: Sarina Canelake <[email protected]> * Update create_github_issue.rst * Update index.rst * Update index.rst * Update index.rst * Update index.rst --------- Co-authored-by: Sarina Canelake <[email protected]>
openedx · Jan 23, 2025 · 83fb23e · 83fb23e
1 parent 25986c2
commit 83fb23e
Show file tree

Hide file tree

Showing 7 changed files with 78 additions and 0 deletions.
diff --git a/source/_images/documentors_howto/issue_template.png b/source/_images/documentors_howto/issue_template.png
diff --git a/source/_images/documentors_howto/issue_template_form.png b/source/_images/documentors_howto/issue_template_form.png
diff --git a/source/_images/documentors_howto/navigation_bar_github.png b/source/_images/documentors_howto/navigation_bar_github.png
diff --git a/source/_images/documentors_howto/new_issue_buttton.png b/source/_images/documentors_howto/new_issue_buttton.png
diff --git a/source/_images/documentors_howto/open_issue_repository.png b/source/_images/documentors_howto/open_issue_repository.png
diff --git a/source/documentors/how-tos/create_github_issue.rst b/source/documentors/how-tos/create_github_issue.rst
@@ -0,0 +1,77 @@
+How to Create a GitHub Issue
+#################################
+
+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.
diff --git a/source/documentors/index.rst b/source/documentors/index.rst
@@ -41,6 +41,7 @@ Open edX Documentors
       * :doc:`how-tos/update_a_doc_via_github`
       * :doc:`how-tos/add_a_doc_via_github`
       * :doc:`how-tos/make_changes_to_your_pull_request`
+      * :doc:`how-tos/create_github_issue`
       +++
       .. button-ref:: how-tos/index
          :color: primary