in-toto doc analysis and recommendations

[jbogarthyde]

resolves: #163
This PR updates and replaces previous PR #190

[dwelsch-esi]

Or remove the "Edit the Docs" button entirely. This seems like a very wiki-ish feature and I'm not sure it belongs in a formal documentation set, even if it does redirect to contributor instructions.

[nate-double-u]

I tend to like the edit the docs button -- remember we're encouraging folks to participate. Opening an issue with a template explaining how best to make suggestions is probably a good thing.

[nate-double-u]

(github issues can have templates: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)

[nate-double-u]

Thanks for this @jbogarthyde! The content here is good, and I agree with the suggestions.

There are some formatting issues throughout that we should fix before merging.

I've not reviewed the issues file yet, i expect those are still a work in progress.

We should update links throughout - you can use https://github.com/jbogarthyde/CNCF-techdocs/tree/main/assessments/0009-in-toto as a deploy preview to check them

[nate-double-u]

let's rename this file assessments/0009-in-toto/issues.md

[nate-double-u]

I think this feels like a heading.

if we use the - [ ] notation, the line will show up like a check box or a todo.

Here, i think we should format to mimic a github issue:

Title: title of the issue

Description:
body copy of the issue (in mark down format)

[nate-double-u]

let's rename this file assessments/0009-in-toto/survey-of-existing-doc.md

[nate-double-u]

Suggested change

	- [Survey of existing documentation](../survey-of-existing-documentation) (as of September 2023)
	- [Analysis](../in-toto-analysis.md)
	- [Recommendations and implementation](../in-toto-implementation.md)
	- [Survey of existing documentation](./survey-of-existing-documentation.md) (as of September 2023)
	- [Analysis](./in-toto-analysis.md)
	- [Recommendations and implementation](./in-toto-implementation.md)

[nate-double-u]

Suggested change

	The [CNCF-techdocs](https://github.com/cncf/CNCF-techdocs/tree/main) group is developing a process aimed at assisting cloud-native open-source projects with their documentation efforts. The process has three steps:
	The [CNCF-techdocs](https://github.com/cncf/techdocs) group is developing a process aimed at assisting cloud-native open-source projects with their documentation efforts. The process has three steps:

[nate-double-u]

Suggested change

	Readers interested only in actionable improvements can skip to the [implementation recommendations](../in-toto-implementation.md). For more context, read the recommendations for each of the three areas of analysis:
	Readers interested only in actionable improvements can skip to the [implementation recommendations](./in-toto-implementation.md). For more context, read the recommendations for each of the three areas of analysis:

[nate-double-u]

Suggested change

	- [Project documentation recommendations](./assessments#recommendations)
	- [Contributor documentation recommendations](./assessments#recommendations-1)
	- [Website recommendations](./assessments#recommendations-2)
	- [Project documentation recommendations](#recommendations)
	- [Contributor documentation recommendations](#recommendations-1)
	- [Website recommendations](#recommendations-2)

[nate-double-u]

Suggested change

	- [Project documentation](./assessments#project-documentation-analysis)
	- [Contributor documentation](./assessments#contributor-documentation-analysis)
	- [Website](./assessments#website-analysis)
	- [Project documentation](#project-documentation-analysis)
	- [Contributor documentation](#contributor-documentation-analysis)
	- [Website](#website-analysis)

[chalin]

Good catch. Somehow, there were not fixed. I've fixed them now.

[nate-double-u]

Thanks!

[nate-double-u]

+1, asking the community folks who have been participating could help here.

[nate-double-u]

I think this will fix the formatting issues

Suggested change

	1. Create **Doc home page**
	The landing page for the [read-the-docs site](https://in-toto.readthedocs.io/en/latest/), which currently lands on the auto-generated Python reference doc, could be expanded and repurposed as the new overall **Doc home page**.
	1.1 To be immediately useful, the landing page should provide a *top-level roadmap* to existing docs. See [Survey of existing doc](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md)
	This is a necessary step in raising the maturity level of this project. The roadmap should initially describe and provide access to:
	- Specification
	- Basic demo
	- Python reference implementation along with its reference docs (which need to move into a sub-directory)
	- Overview of the git repo structure.
	1.2 Move the Description and pointer to the Python Reference implementation to an Implementations section, and move the RTD reference docs for it into this section.
	1.3 Create a doc contributors policy requiring that the Doc home page be updated to reflect any changes to the doc locations and structure.
	1. Create **Doc home page**
	The landing page for the [read-the-docs site](https://in-toto.readthedocs.io/en/latest/), which currently lands on the auto-generated Python reference doc, could be expanded and repurposed as the new overall **Doc home page**.
	1.1 To be immediately useful, the landing page should provide a *top-level roadmap* to existing docs. See [Survey of existing doc](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md)
	This is a necessary step in raising the maturity level of this project. The roadmap should initially describe and provide access to:
	- Specification
	- Basic demo
	- Python reference implementation along with its reference docs (which need to move into a sub-directory)
	- Overview of the git repo structure.
	1.2 Move the Description and pointer to the Python Reference implementation to an Implementations section, and move the RTD reference docs for it into this section.
	1.3 Create a doc contributors policy requiring that the Doc home page be updated to reflect any changes to the doc locations and structure.

[nate-double-u]

Thanks for the updates @jbogarthyde!

We can still make more if needed, but let's get this merged in as is so we can re-start the conversation with the community!

[chalin]

@dwelsch-esi the https://in-toto.io/in-toto/README link is invalid. What was it meant to be?

/cc @nate-double-u

[nate-double-u]

I would guess https://github.com/in-toto/in-toto/blob/develop/README.md, but i think https://in-toto.io/in-toto/ would be more appropriate now.

[nate-double-u]

or maybe @jbogarthyde was suggesting comparing and bringing the one in line with the other?