diff --git a/source/contributing/how-to-migrate.md b/source/contributing/how-to-migrate.md new file mode 100644 index 000000000..4cfc29f11 --- /dev/null +++ b/source/contributing/how-to-migrate.md @@ -0,0 +1,46 @@ +# 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 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: + - 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 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 + 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 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 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 + - Code Formatting + - Tables + - links + - Images and Diagrams \ No newline at end of file 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 ```