Create a guide for migration of docs #544
Conversation
JeremiahSecrist
requested review from
domenkozar and
fricklerhandwerk
as code owners
|
|
||
| 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. |
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.
There was a problem hiding this comment.
This still needs to be addressed
|
There's a handful of places with typos (e.g. "abondoning") and improper English. I'm on my phone or I would point them out individually. Can you make another pass over the document to clean it up? |
There was a problem hiding this comment.
I think in this PR we should focus on one thing only: what to do if you want to include content made by others.
This mainly revolves around licensing and attribution. See also CONTRIBITING.md for some existing hints we should incorporate here as well. Otherwise add some context and motivation (also things such as that reuse is encouraged and attribution required) so readers can be sure they have the right thing in front of them.
This should be as specific to the Nix ecosystem as possible. Luckily when it comes to licenses in general, there is not much to know: don't break the law, give credit where it's due.
We can go into detail for all the other aspects later.
| @@ -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. | |||
There was a problem hiding this comment.
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...)
| 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. |
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.
| 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: |
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.
| 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:
Github Docs CODEOWNERS
Github Docs Blame View
Git-scm git-blame
| 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). |
There was a problem hiding this comment.
Be explicit how to contact them.
| 3. Be sure to identify the type of document that it is easily classifiable as one of the following: | ||
| - Reference | ||
| - Concept | ||
| - Tutorial | ||
| - Recipe |
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.
| - **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? |
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.
| - **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.
| 3. Be sure to identify the type of document that it is easily classifiable as one of the following: | |
| 3. Identify the documentation category the content covers: |
We may want to link to Diataxis here, or maybe defer to the category-specific instructions when they are in place.
| - 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.
This guide covers the issue #518 on how to migrate docs with differing licenses and generic migration as a whole. I personally opted to cover the entirety as licensing is just a part of migration and not substantial enough to be on its own.
Looking for any willing feedback regarding specific re-licensing methodologies that I am not aware of. In addition, do I need to take ownership of this in the CODEOWNERS file? I ask in case someone else is intended to own that directory.