From 844e6c010aca1052578b06de0377a93733d45206 Mon Sep 17 00:00:00 2001 From: Jeremiah S Date: Thu, 11 May 2023 16:47:39 -0400 Subject: [PATCH 1/6] Create a guide for migration of docs. --- source/contributing/how-to-migrate.md | 34 +++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 source/contributing/how-to-migrate.md diff --git a/source/contributing/how-to-migrate.md b/source/contributing/how-to-migrate.md new file mode 100644 index 000000000..eab9d3b08 --- /dev/null +++ b/source/contributing/how-to-migrate.md @@ -0,0 +1,34 @@ +# How to Migrate Documentation - Step-by-Step Process + +Migrating documentation is often crucial when reorganizing any project. As such, below is a list of instructions and guidelines to aid you when embarking on the migration journey. + +1. **Licensing** + 1. Familiarize yourself with the licenses governing the documentation you intend to migrate. + 2. Verify if the license of the documentation is compatible with this project's current license. + 3. If the licenses align, proceed with the migration. Otherwise, follow the steps below. + 4. Identify the file and determine all contributors to the documentation (typically using blame or a co-owners document). + 5. Contact all contributors, requesting permission to migrate the document to the new license. + 6. Await responses from all recipients and obtain explicit approval from each contributor before proceeding. + 7. If agreement from all contributors cannot be obtained, consider alternative solutions to avoid licensing conflicts, such as: + - A full rewrite of the document. + - Rewriting the areas of specific contributors who did not reply or approve. + +2. **Documentation Assessment** + 1. Perform a thorough review of the existing documentation. + 2. Assess the scope, relevance, and quality of the documentation in relation to the migration location. + 3. Consider factors such as: + - Completeness + - Accuracy + - Organization + - Readability + +3. **Version Control and Branching Strategy** + 1. Determine the appropriate branch or repository that contains the most up-to-date or relevant information about the project. In some situations, one might migrate the wrong version if the incorrect branch is specified. + +5. **Validation and Quality Assurance Post Migration** + 1. Ensure consistency in the format and structure of the migrated documentation. + 2. Consider factors like headings, sections, code formatting, tables, and diagrams. + 3. Perform a thorough validation and quality assurance process before finalizing the migration. + 4. Review the migrated documentation for accuracy, completeness, and adherence to desired standards. + 5. Validate code snippets, links, images, and references included in the migrated content. + 6. Conduct usability testing to gather feedback from users and iterate on the documentation based on their input. From 22a60383f6069ff439600202a00f2b9f73fb92b7 Mon Sep 17 00:00:00 2001 From: Jeremiah S Date: Thu, 11 May 2023 17:14:14 -0400 Subject: [PATCH 2/6] Added document to toctree --- source/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/source/index.md b/source/index.md index b3bc44589..ff37fa114 100644 --- a/source/index.md +++ b/source/index.md @@ -77,4 +77,5 @@ contributing/how-to-contribute.md contributing/how-to-get-help.md contributing/documentation.md contributing/writing-a-tutorial.md +contributing/how-to-migrate.md ``` From 25be9997e2d8d371ac3ddee2776b6579231cf269 Mon Sep 17 00:00:00 2001 From: Jeremiah S Date: Sat, 13 May 2023 17:24:15 -0400 Subject: [PATCH 3/6] Created adjustments for @zmitchell review --- source/contributing/how-to-migrate.md | 47 +++++++++++++++++---------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/source/contributing/how-to-migrate.md b/source/contributing/how-to-migrate.md index eab9d3b08..76eec3ec5 100644 --- a/source/contributing/how-to-migrate.md +++ b/source/contributing/how-to-migrate.md @@ -1,11 +1,11 @@ -# How to Migrate Documentation - Step-by-Step Process +# Migrating Documentation Migrating documentation is often crucial when reorganizing any project. As such, below is a list of instructions and guidelines to aid you when embarking on the migration journey. -1. **Licensing** +## Licensing 1. Familiarize yourself with the licenses governing the documentation you intend to migrate. - 2. Verify if the license of the documentation is compatible with this project's current license. - 3. If the licenses align, proceed with the migration. Otherwise, follow the steps below. + 2. Verify that the license of the documentation is compatible with this project's current license. + 3. If the licenses align, proceed with the migration. Otherwise, follow the steps 4 thourgh 7. 4. Identify the file and determine all contributors to the documentation (typically using blame or a co-owners document). 5. Contact all contributors, requesting permission to migrate the document to the new license. 6. Await responses from all recipients and obtain explicit approval from each contributor before proceeding. @@ -13,22 +13,33 @@ Migrating documentation is often crucial when reorganizing any project. As such, - A full rewrite of the document. - Rewriting the areas of specific contributors who did not reply or approve. -2. **Documentation Assessment** +## Documentation Assessment 1. Perform a thorough review of the existing documentation. 2. Assess the scope, relevance, and quality of the documentation in relation to the migration location. 3. Consider factors such as: - - Completeness - - Accuracy - - Organization - - Readability + - Completeness + - Accuracy + - Organization + - Readability + 4. Be sure to identify the type of document that it is easily classifiable as one of the following: + - Reference + - Concept + - Tutorial + - Recipe + 5. If it does not properly classify under step 4 then one will need to consider the following options: + - Rewrite the document to conform + - Split it up into multiple documents + - Abondoning the work entirely if it's not feasible -3. **Version Control and Branching Strategy** - 1. Determine the appropriate branch or repository that contains the most up-to-date or relevant information about the project. In some situations, one might migrate the wrong version if the incorrect branch is specified. +## Version Control and Branching Strategy + Determine the appropriate branch in the repository that contains the most up-to-date or relevant information about the project. In some situations, one often assumes the latest branch is often main or master. Yet in contrast, it can be located in other branches such as beta, next, etc. -5. **Validation and Quality Assurance Post Migration** - 1. Ensure consistency in the format and structure of the migrated documentation. - 2. Consider factors like headings, sections, code formatting, tables, and diagrams. - 3. Perform a thorough validation and quality assurance process before finalizing the migration. - 4. Review the migrated documentation for accuracy, completeness, and adherence to desired standards. - 5. Validate code snippets, links, images, and references included in the migrated content. - 6. Conduct usability testing to gather feedback from users and iterate on the documentation based on their input. +## Visual Quality Assurance + 1. Please make sure the table of contents is structured correctly on the actual site and navigate as expected. + 2. Check the following aspects to function or render as intended: + - Headings + - Sections + - Code Formatting + - Tables + - links + - Images and Diagrams \ No newline at end of file From 4d72d09de992f04eb34787b49af4533deb04e7f0 Mon Sep 17 00:00:00 2001 From: Jeremiah S Date: Sun, 14 May 2023 16:45:24 -0400 Subject: [PATCH 4/6] Fixed spelling and comprehension issues, refactored docs assesment. --- source/contributing/how-to-migrate.md | 41 +++++++++++++-------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/source/contributing/how-to-migrate.md b/source/contributing/how-to-migrate.md index 76eec3ec5..60398ee50 100644 --- a/source/contributing/how-to-migrate.md +++ b/source/contributing/how-to-migrate.md @@ -1,38 +1,35 @@ -# Migrating Documentation - -Migrating documentation is often crucial when reorganizing any project. As such, below is a list of instructions and guidelines to aid you when embarking on the migration journey. - ## Licensing 1. Familiarize yourself with the licenses governing the documentation you intend to migrate. 2. Verify that the license of the documentation is compatible with this project's current license. - 3. If the licenses align, proceed with the migration. Otherwise, follow the steps 4 thourgh 7. - 4. Identify the file and determine all contributors to the documentation (typically using blame or a co-owners document). - 5. Contact all contributors, requesting permission to migrate the document to the new license. + 3. If the licenses align, proceed with the migration. Otherwise, follow the steps 4 through 7. + 4. Identify the file and determine all contributors to the documentation (typically using git blame or a co-owners document). + 5. Contact all contributors, publicly requesting permission to migrate the document to the new license (via issue or pull request). 6. Await responses from all recipients and obtain explicit approval from each contributor before proceeding. - 7. If agreement from all contributors cannot be obtained, consider alternative solutions to avoid licensing conflicts, such as: + 7. If agreement from all contributors cannot be obtained, consider alternative solutions to avoid licensing conflicts such as: - A full rewrite of the document. - Rewriting the areas of specific contributors who did not reply or approve. ## Documentation Assessment - 1. Perform a thorough review of the existing documentation. - 2. Assess the scope, relevance, and quality of the documentation in relation to the migration location. - 3. Consider factors such as: - - Completeness - - Accuracy - - Organization - - Readability - 4. Be sure to identify the type of document that it is easily classifiable as one of the following: + 1. Perform a thorough review of the existing documentation to check for preexisting information. + 2. Consider factors such as: + - **Scope:** Is the topic covered too broad or narrow to be useful? + - **Relevance:** Is this information applicable to what this project is trying to accomplish? + - **Completeness:** If any, what gaps are existing in this information? + - **Accuracy:** If incorrect, is it easy enough to fix or does it warrant a full rewrite? + - **Organization:** How self apparent is the structure of the document, and does it align with the organization of this projects documents? + - **Readability:** How clear is the information when presented to a new reader? + 3. Be sure to identify the type of document that it is easily classifiable as one of the following: - Reference - Concept - Tutorial - Recipe - 5. If it does not properly classify under step 4 then one will need to consider the following options: - - Rewrite the document to conform - - Split it up into multiple documents - - Abondoning the work entirely if it's not feasible + 4. If it does not properly classify under step 3 then one will need to consider the following options: + - Rewrite the document to conform to one of the aforementioned types. + - Split up the document into individual components that can be categorized correctly. + - Abandoning the work entirely if it's not feasible. -## Version Control and Branching Strategy - Determine the appropriate branch in the repository that contains the most up-to-date or relevant information about the project. In some situations, one often assumes the latest branch is often main or master. Yet in contrast, it can be located in other branches such as beta, next, etc. +## Version Control Consideration + Determine the appropriate branch in the repository that contains the most up-to-date or relevant information about the project. This is often assumed to be main or master, yet it can be located in other branches such as beta, next, etc. ## Visual Quality Assurance 1. Please make sure the table of contents is structured correctly on the actual site and navigate as expected. From 13e1a6d5d2ef05626ae10f31b08629eb5114c2e3 Mon Sep 17 00:00:00 2001 From: Jeremiah S Date: Sun, 14 May 2023 16:48:01 -0400 Subject: [PATCH 5/6] language issues on line 35 --- source/contributing/how-to-migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/contributing/how-to-migrate.md b/source/contributing/how-to-migrate.md index 60398ee50..6d21ea624 100644 --- a/source/contributing/how-to-migrate.md +++ b/source/contributing/how-to-migrate.md @@ -32,7 +32,7 @@ Determine the appropriate branch in the repository that contains the most up-to-date or relevant information about the project. This is often assumed to be main or master, yet it can be located in other branches such as beta, next, etc. ## Visual Quality Assurance - 1. Please make sure the table of contents is structured correctly on the actual site and navigate as expected. + 1. Please ensure that the table of contents is structured correctly on the actual site and navigates as expected. 2. Check the following aspects to function or render as intended: - Headings - Sections From 1d80c136568d57ac785651d88a786e97b5e043b2 Mon Sep 17 00:00:00 2001 From: Jeremiah S Date: Sun, 14 May 2023 16:49:43 -0400 Subject: [PATCH 6/6] Fixed accidental removal of heading --- source/contributing/how-to-migrate.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/contributing/how-to-migrate.md b/source/contributing/how-to-migrate.md index 6d21ea624..4cfc29f11 100644 --- a/source/contributing/how-to-migrate.md +++ b/source/contributing/how-to-migrate.md @@ -1,3 +1,7 @@ +# Migrating Documentation + +Migrating documentation is often crucial when reorganizing any project. As such, below is a list of instructions and guidelines to aid you when embarking on the migration journey. + ## Licensing 1. Familiarize yourself with the licenses governing the documentation you intend to migrate. 2. Verify that the license of the documentation is compatible with this project's current license.