Host project-wide usage documentation on in-toto.io

[DarikshaAnsari]

Why raising this issue?

Presently the landing page URL for the read-the-docs site currently hosts the auto-generated Python reference doc and in-toto doc serves the specifications of the project as a content that ultimately confuses the existing general users. So our aim is to serve a dedicated Project-wide docs on in-toto.io. See the discussion regarding this here.

Possible changes

• Utilizing static site generator for project-wide docs that is already provided by in-toto.io.
• Developing the content to be served as the Project-wide docs including the technical specifications, usage of the project and other important features that are being used by the users in order to explore true capabilities of in-toto as the service.

Expected Outcome

After setting up a structured approach to the problem and proceeding with the implementation steps we would ultimately be able to serve the existing/new users with the dedicated project wide documentation at one place i.e in-toto.io rather maintaining it over two places that ultimately confused the users.

[lukpueh]

Thanks for transferring the issue, @DarikshaAnsari! The umbrella docs issue and referenced issues in the in-toto/docs repo already provide a good roadmap for creating the structure and adding content.

I suggest to move forward as described there, except that the mentioned site structure isn't created in in-toto/docs and built with a new static site generator, but here in this repo, e.g. in a new directory in-toto/in-toto.io/content/docs, and built with the existing in-toto.io Hugo site generator.

[DarikshaAnsari]

Hey @lukpueh, thanks for sharing the resources, What I gathered from umbrella docs issues, it seems that we need to replicate the process we use for creating the homepage on the repo in-toto.io

[lukpueh]

I just transferred the original issue from in-toto/docs to this repo --> in-toto/specification#34. Let's continue the discussion there.