Develop a user doc contribution policy

[jbogarthyde]

UPDATE 05/27/2024 (transfer issue from in-toto/docs)

• [ ] Specify user doc source location. Source files for all web-based user doc content goes into ~[https://github.com/in-toto/docs]/source~ in-toto.io/docs (see https://github.com/in-toto/in-toto.io/issues/34)
• [ ] Specify user doc approvers and resources. Add specific information in the contribution policy about who can review and approve changes and additions to user docs, and resources available to writers and editors. Include or link to:
  • Contact info for maintainer/reviewer for documentation contributions.
  • Available doc style guides/templates (as well as code standards)
  • Usage guidelines for RTD (or other doc tool) and any project-specific usage standards.
  • Current doc architecture plan.
  • Map to documentation source files.

[Ayush9026]

/assign @Ayush9026 i will solve this issue.

[nate-double-u]

Hello, Thanks for your interest!

If you're looking to participate in the LFX Mentorship program, the best path is to apply via the LFX platform. Assignment on this particular issue before being accepted is premature.

[DarikshaAnsari]

@lukpueh, could you please assist me with this issue as well? I'm completely unsure where to start and could really use some additional guidance or references. Thank you!

[lukpueh]

Hm. Let's take a look at what the assessment says...

• [ ] Specify user doc source location. Source files for all web-based user doc content goes into ~[https://github.com/in-toto/docs]/source~ in-toto.io/docs (see Create Doc Home Page in-toto.io#34)

General doc source location should be: https://github.com/in-toto/in-toto.io And, more specifically, the user doc source location will be https://github.com/in-toto/in-toto.io/tree/main/content/en/docs after you migrated your docsy page upstream, right?

• [ ] Specify user doc approvers and resources. Add specific information in the contribution policy about who can review and approve changes and additions to user docs, and resources available to writers and editors. Include or link to:

  • Contact info for maintainer/reviewer for documentation contributions.

I'm against listing individual contact infos. Maintainers/reviewers usually get notified, when an issues is created. So let's instead update the community contributing policy to point folks to the in-toto.io repo and ask them to raise docs issues and submit docs PRs there.

Additionally, we can add a link to our general contact page, which will be https://in-toto.io/community/#learn-and-connect (after migration).

• Available doc style guides/templates (as well as code standards)

I don't think we have any.

• Usage guidelines for RTD (or other doc tool) and any project-specific usage standards.

Those should be in project-specific contributing policies. For docs specifically, we should point to https://github.com/in-toto/in-toto.io/blob/main/CONTRIBUTING.md in

• Current doc architecture plan.
• Map to documentation source files.

IMO it doesn't have to be a plan or map. So to recap above comments, I'm okay if we make the following updates to resolve this issue...

In community contributing policy:

• for reference docs, point out that they are sub-project specific (e.g. RTD)
• for general project docs, point to docs website, docs sources and docs contributing policy
• (bonus) polish the whole document to make it less opinionated for (python) code contributions. IMO the purpose of this doc is to give an overview of the many ways of contributing to the in-toto project (code or docs), and then forward contributors to sub-project-specific contribution docs.

In docs contributing policy:

• maybe explain a bit how general docs are structured on in-toto.io (I'm fine if you just create an issue about this in the in-toto.io repo for now)