Closed SteveLasker closed 3 years ago
My preference is for option 1
pros:
cons:
A lot of the pros listed for option 2 are cons for me, since independent merges and tracking docs separately means we'll get inconsistencies between the documentation and the code. It's hard enough to keep them in sync even when the docs are in the same repo since not every developer remembers to update them.
Whether missing documentation causes a merge to be blocked is a decision for that sub-project to make. They can allow the docs to diverge and have separate commits to the code and the docs direction in their project. But if they want the ability to have consistency, they can only enforce that with option 1.
+1 for 1
Are the doc writers and code contributors/approvers the same person/team? If yes, then option 1. If not, then option 2
I agree that option 1 will have a better chance of keeping docs and code in sync.
Dev docs especially (build/test) etc. living with the repo enables other developers to contribute faster.
However the set of docs for e2e scenarios and assets like images, that are specific to use cases, and websites, living in its own repository might enable the doc iteration to happen independently.
Both models exist - My preference is to keep image assets out of the cli/library repo from the start if possible.
Hi I'm working on Notary Project docs and the notaryproject.dev website on behalf of the CNCF 👋🏻
If system 1 (docs in multiple project repos) implies that there is also copy in the website repo, then it requires the duplication of content through automated (or worse, manual) means.
If system 1 implies that the website just links out to the various docs repo's /docs
folder, then I think we lose out on a lot of value that having a website for the documentation provides (including managing images and multimedia more easily, as @sajayantony mentions)
If the maintainers do decide to keep a canonical copy of the documentation in the project repo, I'd suggest that we pull those docs into the notaryproject.dev repo using git submodules.
@chalin lays out the advantages and disadvantages of submoduling for the OTel project
Disadvantages of file mirroring and copying:
- We lose true edit/blame history - There's the risk of edits being done in the wrong place (since files are present in two repos) - There's potential confusion of where to open issues (again, since files are present in two repos)
Advantages of using submodules (other than the counterpart of the disadvantages listed above):
- Website maintainers can bring in doc updates from all language repos with a single command
In the end, it looks like OTel went with a system that ensures that there is only ever one copy of the docs.
System 2 (docs only in the notaryproject.dev repo) is used by some large multi repo projects in the CNCF (most notably the Kubernetes website).
Regardless of the system chosen, I'd strongly recommend that there be only one canonical place for documentation to be written.
permissions a bit more complicated for who has merge rights on the notaryproject.dev repo
We've setup the notaryproject.dev repo with a .github/settings.yml file, we can add subproject leads with a PR. Hopefully this simplifies the merge rights a bit. 🙂
I meant to add this to our weekly agenda for discussion. I'm hearing more hesitation about pushing content to sub /doc/
folders than seems reflected here.
To get unblocked, I'll suggest we start getting docs into a /docs/
subfolder in the sub-projects and let us discuss next week.
If anyone can point to other projects that have done it either way, with a process/toolset that would enable the "upstreaming" of content from sub-projects to the notaryproject.dev website, that would be helpful to get closure.
Another advantage for combining the documentation into one site that I had forgot to mention:
@nate-double-u, assuming you can make the call tomorrow, I've assigned closure of the topic to you :) https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw
Option 2 was selected during today's community meeting.
Documentation should be placed in the projectnotary.dev repo; however, since some sub-projects are still early in their initial development, links to those project's GitHub repo (/docs
folder) can be provided until such a time as it's appropriate to move those project's docs.
The current documentation project board can be moved out of the notaryproject.dev repo and up to the org level to help organize and track this work.
Contribution guidelines for the projects should be updated, and a docs contributions guideline should be written (if there isn't one already) to help developers, maintainers, and writers know how to get their docs in.
notaryproject/notaryproject.dev/.github/settings.yml to be updated with the sub-project leads so that they can approve documentation PRs.
/close
Closing per notes from @nate-double-u
Should we:
/notation/docs/
,/notation-go/docs
,/tuf/docs/
, etc.notaryproject.dev
repogit clone
of docs and code are separatednotaryproject.dev
repo