How to document notary project content

[SteveLasker]

Should we:

1. place documents within /notation/docs/, /notation-go/docs, /tuf/docs/, etc.
   • pros
     • devs can commit their code and docs in one pr
     • reviewers can review and commit the prs in one shot
     • permissions of the docs and code are consistent
   • cons
     • devs get blocked from merging their code, based on the content of the docs
     • git clone of the source, pulls in docs
2. place docs in the notaryproject.dev repo
   • pros
     • code is reviewed and merged independently
     • code is tracked separately from docs. git clone of docs and code are separated
     • less complication for how the docs are built, as all the content is in one repo
   • cons
     • permissions a bit more complicated for who has merge rights on the notaryproject.dev repo

[sudo-bmitch]

My preference is for option 1

pros:

• Code and doc changes are approved at the same time
• People that understand what is changing are more likely to be the ones making the doc changes

cons:

• May be more complicated to implement
• Cloning the docs repo only retrieves some common core components (unless we use git submodules which I'd recommend against for this)

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.

[trishankatdatadog]

+1 for 1

[iamsamirzon]

Are the doc writers and code contributors/approvers the same person/team? If yes, then option 1. If not, then option 2

[mnm678]

I agree that option 1 will have a better chance of keeping docs and code in sync.

[sajayantony]

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.

• https://github.com/grafana/grafana/tree/main/docs

• https://github.com/open-policy-agent/opa/tree/main/docs

• https://github.com/kubernetes/website

• https://github.com/prometheus/docs

• https://github.com/helm/helm-www

• https://github.com/coredns/coredns.io

• https://github.com/containernetworking/cni.dev

[nate-double-u]

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.

• this automation needs to be set-up and maintained. This requires people willing to maintain it for the long term, and may require a different skill set than is normally required of someone contributing to these projects.
• duplication content isn't ideal, for instance: I believe that Google indexes the master branch. This may be different now, or it may have been updated to index the main branch, but this sort of duplication can cause problems for discoverability.
• Linking within the site becomes more complex when the content is spread across multiple repos. Which is the primary destination: the website, or the sub-project repo.

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.

[nate-double-u]

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. 🙂

[SteveLasker]

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.

[nate-double-u]

Another advantage for combining the documentation into one site that I had forgot to mention:

• localization/translation is managed much more easily on a site setup for it (like Hugo/Docsy is), than in individual repos. This may be a long term consideration, but is worth planning for.

[SteveLasker]

@nate-double-u, assuming you can make the call tomorrow, I've assigned closure of the topic to you :)
https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw

[nate-double-u]

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

[SteveLasker]

Closing per notes from @nate-double-u