Create a guide for migration of docs #544
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| # 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. | ||
| 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. | ||
|
Comment on lines
+9
to
+14
Contributor
There was a problem hiding this comment. We could have that a separate section and link to that from the last instruction of the license assessment.
Contributor
Author
There was a problem hiding this comment. Are there other situations that warrant license consideration outside migration of documentation for this project specifically? Depending on how much this needs to be expanded upon, I can understand moving it to its own document regardless of the prior question. At present, I don't see enough information needed to warrant it. To be clear, I'm not saying no in the stricter sense. More so, I am looking for the scenario that justifies it.
Contributor
There was a problem hiding this comment. No. I was just suggesting taking it out of the list and have separate one. But the broader issue of focusing on just the licensing in this PR actually obviates this particular comment. |
||
|
|
||
| ## 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. | ||
|
Contributor
There was a problem hiding this comment. It's not clear to me what "quality of the documentation in relation to the migration location" means.
Contributor
There was a problem hiding this comment. This still needs to be addressed |
||
| 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: | ||
| - Reference | ||
| - Concept | ||
| - Tutorial | ||
| - Recipe | ||
|
Comment on lines
+25
to
+29
Contributor
There was a problem hiding this comment. Maybe that should be the first step? Once you have a hunch something is good and it's freely licensed (the details can be figured out later), the most important thing is to check if it can find an obvious place to live in official documentation. |
||
| 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 | ||
|
|
||
| ## 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. | ||
|
|
||
| ## 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 | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this needs a bit of motivation. Something like that there is a lot of good stuff out there. You may find a piece of writing that covers a topic you want documented very nicely. But different projects, repositories, groups of people - for various reasons - put their work under free but different and possibly incompatible licenses, which may preclude using it for our purposes straight away. (Please don't take this verbatim...)