Umbrella Issue: CNCF Tech Doc Recommendations

[jbogarthyde]

UPDATE 05/27/2024 (transfer sub-issues, update issue description)

Umbrella issue

This is a checklist for the CNCF technical documentation analysis and implementation plan. It should be updated as sub-issues are added, completed, or otherwise modified. All related Issues should be given the Documentation label.

This issue tracks recommended changes resulting from an analysis of the in-toto documentation commissioned by CNCF.

• The CNCF in-toto documentation effort is tracked in the CNCF Tech Docs repo: https://github.com/cncf/techdocs/pull/200
• For a more detailed description, see analysis and supporting documents.

The goal for these changes is to develop web-based documentation aimed explicitly at users, and distinguish the user documentation from the documentation intended for contributors.

There are three distinct audiences for user documentation that require introductory information at different levels of detail:

• A basic intro suitable for evaluators and potential adopters is already linked directly from the home page About tab.
• The mid-level overview in https://github.com/in-toto/in-toto/blob/develop/README.md is aimed specifically at users - that is, adopters who are integrating an implementation into their own workflows, and the project owners who will create layouts.
• The low-level, comprehensive technical overview in the in-toto Technical Specification is primarily aimed at contributors.

User doc sub-issues

This is a list of issues representing the recommended work on the in-toto website and technical documentation for users.

Create home page for user documentation on website

To be immediately useful, the landing page should provide a top-level roadmap to existing docs. This is a necessary step in raising the maturity level of this project.

~The landing page URL for the read-the-docs site currently hosts the auto-generated Python reference doc. To use Read the Docs as the site generator, expand and repurpose this URL as the new overall Doc Home Page, add user-doc build files in user-doc source directory, and modify the destination for the reference-doc build.~

• [ ] https://github.com/in-toto/in-toto.io/issues/34

Expose new-user information on website

Information that is needed by new users is currently in GitHub readme files and in the Specification. Adapt and move the information to source files for the web-based documentation.

• [ ] https://github.com/in-toto/in-toto.io/issues/35

• [ ] https://github.com/in-toto/in-toto.io/issues/36 Copy sections of the in-toto Technical Specification into source for a system overview page.

• [ ] https://github.com/in-toto/in-toto.io/issues/37

Contributor doc sub-issues

This is a list of issues representing the recommended work on supporting contributions to documentation. Contributor policies for documentation can remain in GitHub, in the https://github.com/in-toto/community repo. See https://github.com/in-toto/community/issues/9

• [ ] https://github.com/in-toto/community/issues/28

• [ ] https://github.com/in-toto/in-toto/issues/755

• [ ] https://github.com/in-toto/community/issues/30 The policy for contributing to user documentation specifies how and where to make additions and changes to existing user documentation.

[jbogarthyde]

Please add the documentation label to this issue

[Ayush9026]

@jbogarthyde sir i am interested in this issue under mentorship.

[lukpueh]

@Ayush9026, I think this one needs some planning first...

@jbogarthyde, thanks for the detailed analysis and clear plan for action! This all sounds very reasonable. I only have a minor concern about hosting project-wide usage docs together with Python reference implementation docs on RTD (see https://github.com/in-toto/in-toto.io/issues/34 for details).

Is there a specific reason to not implement the above plan on in-toto.io? From what I see, you also floated this idea in the assessment, although only as temporary solution, which isn't described here in the umbrella issue anymore.

IMO the Hugo static site generator, used for in-toto.io, is a good fit for usage docs (it supports Markdown). So I suggest we do start as you describe it in your assessment, that is, "Create a Documentation home page on the project web site", and then we add the content described here and in in-toto/in-toto.io#34, in-toto/in-toto.io#35, in-toto/in-toto.io#36 and in-toto/in-toto.io#37 to that page.

[maanugh]

Why maintain a separate docs repository? Let's include the docs in this repo to simplify maintenance. https://github.com/in-toto/in-toto.io

// @lukpueh

[Snehaaa18]

I am interested in contributing under the mentorship . I want to connect and understand the process for contributing to increase my chances of getting selected.

[lukpueh]

☝️ FYI, I just transferred the sub-issues referenced above from this repo to in-toto/in-toto.io and in-toto/community respectively.

The plan remains the same, with the only difference that the new "Usage Documentation Page" will be hosted on in-toto.io (and its source in the in-toto/in-toto.io repo). The issue descriptions have been updated accordingly.

[chalin]

@lukpueh - shouldn't this issue also be moved to https://github.com/in-toto/in-toto.io since it's all about docs?