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,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). | ||||||
|
There was a problem hiding this comment. Please link to authoritative documentation on these technical terms. I have never seen such a thing as a co-owners document. And most people won't know how to use git blame. Linking to GitHub's instructions additionally won't hurt. There was a problem hiding this comment. I'll gather some here soon for approval before I wastefully write them in. There was a problem hiding this comment. I came across the following links: |
||||||
| 5. Contact all contributors, publicly requesting permission to migrate the document to the new license (via issue or pull request). | ||||||
|
There was a problem hiding this comment. Be explicit how to contact them. |
||||||
| 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: | ||||||
|
There was a problem hiding this comment. Another option is to keep the license as is and somehow note that in the document. There was a problem hiding this comment. Some agreements would need to be made here on how to do that in this project specifically before I start writing via my own assumptions. There was a problem hiding this comment. I noted in the relicensing issue that we probably don't have much choice anyway apart from not using material not under CC. The question really is whether and how to deal with multiple licenses. |
||||||
| - A full rewrite of the document. | ||||||
| - Rewriting the areas of specific contributors who did not reply or approve. | ||||||
|
Comment on lines
+9
to
+14
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. 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. 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 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? | ||||||
|
Comment on lines
+19
to
+20
There was a problem hiding this comment. This is not actionable. I wouldn't know what to do. Maybe we should postpone dealing with these questions in separate instructions for the different documentation categories. This actually holds for all items in the sublist. The exact instructions will be quite specific, so we may want to just refer to those. Since we don't have them yet, let's focus on getting information on the licensing issue merged first. |
||||||
| - **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: | ||||||
|
There was a problem hiding this comment.
Suggested change
We may want to link to Diataxis here, or maybe defer to the category-specific instructions when they are in place. |
||||||
| - Reference | ||||||
| - Concept | ||||||
| - Tutorial | ||||||
| - Recipe | ||||||
|
Comment on lines
+25
to
+29
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. |
||||||
| 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. | ||||||
|
There was a problem hiding this comment. I don't think this applies for us. There was a problem hiding this comment. This was in terms of other repositories they may be pulling information from for consolidation. |
||||||
|
|
||||||
| ## 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 | ||||||
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...)