sigstore / docs

Sigstore documentation
https://sigstore.dev
MIT License
72 stars 80 forks source link

Include visualisations to enhance user understanding when going through the docs #140

Open DMills27 opened 1 year ago

DMills27 commented 1 year ago

Description

The inclusion of more visualisations such as diagrams, flowcharts, and/or gifs would greatly benefit the documentation website. This is apparent in sections such as How Sigstore works and Software supply chain security and where the descriptions given lends itself to more visual imagery. Moreover, In the Main Concepts page, it is mentioned that “[the various sigstore technologies] can be used independently or as one single process,” yet this seems like a missed opportunity to use a diagram to Illustrate this. Visualisations reduce ambiguity and potential misunderstandings by providing a clear and precise representation of the information being conveyed. The sigstore documentation website has many sections that could be better elucidated with the addition of visual components.

Interestingly, the sigstore.dev site does a better job of utilising visualising the relationships between sigstores constituent repositories, as shown below.

sigstore homepage image

Creating visualisations in a manner consistent with the rest of the site as shown in the above image would make the documentation much easier to understand compared to purely textual descriptions.

git-maniesh commented 1 year ago

I am looking forward to contribute over this issue .. hope you would help me in assisting the task and gain myself in the GSoD 2023

Neilblaze commented 1 year ago

@DMills27 I do agree! Adding visualizations will surely enhance the top-down view & simplify the readability of the flow.