Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Umbrella Issue: CNCF Tech Doc Recommendations #46

Open
3 of 7 tasks
jbogarthyde opened this issue Jan 24, 2024 · 7 comments · Fixed by #53
Open
3 of 7 tasks

Umbrella Issue: CNCF Tech Doc Recommendations #46

jbogarthyde opened this issue Jan 24, 2024 · 7 comments · Fixed by #53
Labels
documentation Improvements or additions to documentation

Comments

@jbogarthyde
Copy link

jbogarthyde commented Jan 24, 2024

UPDATE 05/01/2024 (transfer issue)
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 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:

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.

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.

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 in-toto/community#9

@jbogarthyde
Copy link
Author

Please add the documentation label to this issue

@Ayush9026
Copy link

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

@lukpueh lukpueh added the documentation Improvements or additions to documentation label May 13, 2024
@lukpueh
Copy link
Member

lukpueh commented May 13, 2024

@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 #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 #34, #35, #36 and #37 to that page.

@maanugh
Copy link

maanugh commented May 16, 2024

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
Copy link

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
Copy link
Member

lukpueh commented May 27, 2024

☝️ 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
Copy link
Collaborator

chalin commented Jun 27, 2024

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

@lukpueh lukpueh transferred this issue from in-toto/specification Jul 1, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants