-
Notifications
You must be signed in to change notification settings - Fork 59
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
FC-0068 create doc maintenance (#802)
* FC-0068 create doc maintenance This PR creates the doc maintenance chart and process. * Update doc_maintanace.rst * Update doc_maintanace.rst * Update doc_maintanace.rst * Update and rename doc_maintanace.rst to doc_maintenance.rst * Update doc_maintenance.rst * Update doc_maintenance.rst * Update doc_maintenance.rst * Update source/documentors/references/doc_maintenance.rst Co-authored-by: Sarina Canelake <[email protected]> * Update source/documentors/references/doc_maintenance.rst Co-authored-by: Sarina Canelake <[email protected]> * Update source/documentors/references/doc_maintenance.rst Co-authored-by: Sarina Canelake <[email protected]> * Update doc_maintenance.rst * Update doc_maintenance.rst * Update doc_maintenance.rst * Update doc_maintenance.rst * Update doc_maintenance.rst * Update doc_maintenance.rst --------- Co-authored-by: Sarina Canelake <[email protected]>
- Loading branch information
1 parent
83fb23e
commit a483861
Showing
1 changed file
with
147 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| Documentation Maintenance Process | ||
| ############################################ | ||
|
|
||
| .. contents:: Contents | ||
| :local: | ||
| :depth: 2 | ||
|
|
||
| Introduction | ||
| ************* | ||
|
|
||
| This document aims to establish a maintenance process for the community to keep Open edX documents current and accurate. | ||
|
|
||
| Purpose | ||
| ******** | ||
|
|
||
| The purpose of this document is to provide a standardized process for contributors who maintain existing documentation. Maintenance involves reviewing and testing existing documents, fixing issues, or submitting reports when they are outdated or inaccurate. | ||
|
|
||
| This process ensures consistent standards among contributors and improves documentation quality assurance (QA). | ||
|
|
||
| Roles and Responsibilities | ||
| **************************** | ||
|
|
||
| User: Even without the official role of contributor, any user of the Open edX documentation may text and report errors in the documentation. | ||
|
|
||
| Contributors: Review and test documents, update the Maintenance Chart and submit pull requests or issues for fixes. | ||
|
|
||
| Working Groups: Collaborate on unresolved issues, oversee compliance with standards, and ensure documentation QA. | ||
|
|
||
| Maintenance Procedure | ||
| *********************** | ||
|
|
||
| The maintenance process involves reviewing and, if applicable, following the steps in the document on a stable and current Open edX release and either: | ||
|
|
||
| A. Mark the document as "passing" - that is, everything is accurate. | ||
| B. Mark the document as "failing" and submit an issue to fix an error. | ||
| C. Fixing an error and changing the document's status from "fail" to "pass". | ||
|
|
||
| During this process, the user or contributor should read the document carefully and pay attention to the following details: | ||
|
|
||
| - Images | ||
| - Links | ||
| - Diataxis type (how-to, quickstart, concept, reference) | ||
| - Process | ||
| - Correctness of information | ||
| - Open edX version | ||
|
|
||
| The user must also consider the standards previously defined in the :doc:`../concepts/content_types` and :doc:`doc_style_guide`. | ||
|
|
||
| Steps to follow to comply with the maintenance procedure | ||
| ********************************************************* | ||
|
|
||
| 1. Pick one document to be reviewed. | ||
| 2. Confirm that the document meets the standards in the :doc:`doc_checklist`: | ||
|
|
||
| a. Audience is defined | ||
| b. The Diataxis type is defined | ||
| c. RST standards are followed | ||
| d. Images are working and current | ||
| e. External links are working and accurate | ||
| f. ``See Also table`` is included | ||
|
|
||
| 3. While reading the document, consider the standards defined in the :doc:`doc_style_guide` (be focused on Grammar, details, etc). | ||
| 4. Based on the diataxis type, test or validate the document: | ||
|
|
||
| a. If the document is a **how-to** or **quickstart**, complete the steps as instructed and confirm that the outcome in your Open edX instance is the same as what the doc expects. | ||
| b. If the document is a **reference**, confirm that the reference is complete and matches what you observe in your current Open edX version. | ||
| c. If the document is a **concept**, confirm that the information is accurate and up-to-date. | ||
|
|
||
| 5. Complete the maintenance chart (following the instructions below). | ||
|
|
||
| Maintenance Chart | ||
| ******************* | ||
|
|
||
| This chart will be included in every Open edX document so that each user can perform their test. | ||
| It should be completed once the user completes the review process. All fields are required except for the name of the user. | ||
|
|
||
| .. list-table:: | ||
| :header-rows: 1 | ||
|
|
||
| * - Review Date | ||
| - Working Group Reviewer | ||
| - Release | ||
| - Test Situation | ||
| * - 2025-06-01 | ||
| - Documentation WG - Ana Gomez | ||
| - Sumac | ||
| - Pass | ||
| * - 2025-12-01 | ||
| - Documentation WG | ||
| - Verawood | ||
| - `Fail <https://github.com/openedx/docs.openedx.org/issues/776>`_ | ||
| * - 2025-12-15 | ||
| - BTR WG | ||
| - Verawood | ||
| - Pass | ||
|
|
||
| To apply the maintenance chart on a new document, you can use the following code: | ||
|
|
||
| .. code-block:: RST | ||
| .. list-table:: | ||
| :header-rows: 1 | ||
| * - Review Date | ||
| - Working Group Reviewer | ||
| - Release | ||
| - Test Situation | ||
| * - 2025-06-01 | ||
| - Documentation WG - Collaborator's name | ||
| - Sumac | ||
| - Pass | ||
| * - 2025-12-01 | ||
| - Documentation WG | ||
| - Verawood | ||
| - `Fail <<https://github.com/openedx/docs.openedx.org/issues/XXXX>`_ (replace XXXX with the issue number) | ||
| * - 2025-12-15 | ||
| - BTR WG | ||
| - Verawood | ||
| - Pass | ||
| Review Date | ||
| =========== | ||
|
|
||
| The user should add the month and year of the review using the following format: YYYY-MM-DD. | ||
|
|
||
| Working Group Reviewer | ||
| ====================== | ||
|
|
||
| This field should contain the name of the Working Group to which the user belongs. Including individual names is optional. | ||
|
|
||
| Release | ||
| ======== | ||
|
|
||
| This field indicates the Open edX version on which the test was performed. | ||
|
|
||
| Test Situation | ||
| =============== | ||
|
|
||
| In this column, the user should state if the review process (test) is passed or failed, writing “Pass” or “Fail”. | ||
|
|
||
| If the test passes, the document does not need any change, which means that every link works, there is no need to add any new information, the diataxis criteria are good, etc. However, if the test fails, the contributor can take either of two actions: | ||
|
|
||
| 1. :doc:`Submit a PR with a fix <../how-tos/update_a_doc_via_github>` and link to the PR in the Failure flag. | ||
|
|
||
| 2. Create a GitHub issue and link it to the issue in the Failure flag so someone else is aware of the error and can fix it. | ||
| :doc:`Check this how-to doc for creating GitHub issues <../how-tos/create_github_issue>`. | ||
|
|
||
|
|