From 03ca321b1589c1a7cbc416486689f25f4b3f5c51 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Tue, 18 Jun 2024 14:52:31 +0300 Subject: [PATCH 01/96] Docs: Create TUF docs analysis folder Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/README.md | 0 analyses/0012-TUF/TUF-Implementation.md | 0 analyses/0012-TUF/TUF-analysis.md | 138 ++++++++++++++++++++++++ analyses/0012-TUF/TUF-issues.md | 0 4 files changed, 138 insertions(+) create mode 100644 analyses/0012-TUF/README.md create mode 100644 analyses/0012-TUF/TUF-Implementation.md create mode 100644 analyses/0012-TUF/TUF-analysis.md create mode 100644 analyses/0012-TUF/TUF-issues.md diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md new file mode 100644 index 0000000..e69de29 diff --git a/analyses/0012-TUF/TUF-Implementation.md b/analyses/0012-TUF/TUF-Implementation.md new file mode 100644 index 0000000..e69de29 diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md new file mode 100644 index 0000000..01515d5 --- /dev/null +++ b/analyses/0012-TUF/TUF-analysis.md @@ -0,0 +1,138 @@ +--- +title: TUF Documentation Analysis +tags: TUF +created: 2024-06-17 +modified: YYYY-MM-DD +author: Sandra Dindi (@Dindihub) +--- + +## Introduction + +This document analyzes the effectiveness and completeness of +[The Update Framework](https://theupdateframework.io) (TUF) open source software (OSS) project's documentation +and website. It is funded by the CNCF Foundation as part of its overall effort +to incubate, grow, and graduate open source cloud native software projects. + +According to CNCF best practices guidelines, effective documentation is a +prerequisite for program graduation. The documentation analysis is the first +step of a CNCF process aimed at assisting projects with their documentation +efforts. + +### Purpose + +This document analyzes the current state of **The Update Framework (TUF)** +documentation. It provides project leaders with an informed understanding +of potential problems in current project documentation. A second [TUF-impementation.md](./TUF-implementation.md) +document, , outlines an actionable plan for improvement. A third document, the +[TUF-issues.md](./TUF-issues.md) outlines issues to be added to the project documentation repository. These +issues can be taken up by contributors to improve the documentation. + +This document: + +- Analyzes the current TUF technical documentation and website +- Compares existing documentation against the CNCF’s standards +- Recommends a program of key improvements with the largest return on investment + +### Scope of analysis + +The documentation includes the entire contents of the website, +the technical documentation, and documentation for contributors and users on the TUF GitHub repository. + +The TUF website and documentation are written in Markdown and compiled using the Hugo static site generator and served on the Netlify platform. The site's code is stored on the TUF GitHub +repo. + +#### In scope + +- Website: https://theupdateframework.io +- Documentation: https://theupdateframework.io/content +- Website configuration(Hugo): https://github.com/theupdateframework/theupdateframework.io + + +#### Out of scope + +- The TUF community repository: https://github.com/theupdateframework/community +- TUF specification repository: https://github.com/theupdateframework/specification +- Python reference implementaion reposiroty: https://github.com/theupdateframework/python-tuf +- TUF Augmentation proposals respsitory: https://github.com/theupdateframework/taps +- TUF artwork repository: https://github.com/theupdateframework/artwork + + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** Analyzes documentation for users of the TUF project + software. +- **Contributor documentation:** Analyzes documentation for existing and new contributors to TUF project. +- **Website:** Analyzes the mechanics of publishing the documentation, including branding, website structure, and maintainability. + +Each section begins with summary ratings based on a rubric with appropriate +[criteria] for the section, then proceeds to: + +- **Comments**: Observations about the existing documentation, with a focus on + how it does or does not help TUF project users achieve their goals. +- **Recommendations**: Suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [implementation](./TUF-implementation.md) document breaks the recommendations down into +concrete actions that can be implemented by project contributors. Its focus is +on drilling down to specific, achievable work that can be completed in +constrained blocks of time. + +Ultimately, the implementation items are decomposed +into a series of [issues](./TUF-issues.md) that can be implemented by the project maintainers. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the **[implementation](./TUF-implementation.md) plan** and **[issues](./TUF-issues.md) list**. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation]() +- [Contributor documentation]() +- [Website and documentation infrastructure]() + + +#### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards, +and suggests possible improvements. In most cases there is more than one way to +do things. Few recommendations here are meant to be prescriptive. Rather, the +recommended implementations represent the reviewers' experience with how to +apply documentation best practices. In other words, borrowing terminology from +the lexicon of [RFCs][rfc-spec], the changes described here should be understood +as "recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. + +## Project documentation + + +| Criteria | Rating (1-5) | +| -------------------------- | -------------- | +| Information architecture | 3 | +| New user content | 1 | +| Content maintainability | 3 | +| Content creation processes | 1 | +| Inclusive language | 3 | + +Scale: + +- 1 = (Is not present) +- 3 = (Is present, but needs improvement) +- 5 = (Is executed extremely well or no improvement required) + +### Comments +The following sections contain brief assessments of each element of the Project +Documentation rubric. + +#### Information architecture + +- There is an overview section explaining what TUF is and its use cases. The features, the metadata and roles are well explained with examples for each metadata. + +- No tutorials for specific feature implementation. But, there are videos explaining various use cases. + diff --git a/analyses/0012-TUF/TUF-issues.md b/analyses/0012-TUF/TUF-issues.md new file mode 100644 index 0000000..e69de29 From 2d973959cee8ddd4808cb2fda4e72dc620019ae3 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Tue, 18 Jun 2024 16:37:57 +0300 Subject: [PATCH 02/96] Docs: Add content to analysis doc Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index 01515d5..a36d176 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -128,11 +128,26 @@ Scale: ### Comments The following sections contain brief assessments of each element of the Project -Documentation rubric. +documentation rubric. #### Information architecture - There is an overview section explaining what TUF is and its use cases. The features, the metadata and roles are well explained with examples for each metadata. +- Repetition of content on different pages + +- Content needs to be re-organised to make it easier to follow + - No tutorials for specific feature implementation. But, there are videos explaining various use cases. +- No specific task-based guide for features. The available guide for implementing the specification is part of a larger document labelled 'Specification latest' + +- There's a FAQ and reporting issues sections for troubleshooting. + +- There's an API reference for multiple TUF APIs + +- README on documentation repo is empty with no information about it's content. + + +#### New user content + From 919bff35fc1c491f26f3b0e9049fe31e1f25553f Mon Sep 17 00:00:00 2001 From: Dindihub Date: Wed, 19 Jun 2024 20:20:07 +0300 Subject: [PATCH 03/96] Add signoff in commit Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index a36d176..5e7b035 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -134,20 +134,36 @@ documentation rubric. - There is an overview section explaining what TUF is and its use cases. The features, the metadata and roles are well explained with examples for each metadata. -- Repetition of content on different pages +- Repetition of content on different pages makes content confusing - Content needs to be re-organised to make it easier to follow -- No tutorials for specific feature implementation. But, there are videos explaining various use cases. +- Docs do not have tutorials for specific feature implementation. But, there are videos explaining various use cases. -- No specific task-based guide for features. The available guide for implementing the specification is part of a larger document labelled 'Specification latest' +- There are not specific task-based guides for features. The available guide for implementing the specification is part of a larger document labelled 'Specification latest' -- There's a FAQ and reporting issues sections for troubleshooting. +- There is a FAQ and reporting issues sections for troubleshooting. -- There's an API reference for multiple TUF APIs +- There is a a well detailed API reference for multiple TUF APIs -- README on documentation repo is empty with no information about it's content. +- README on theupdateframework.io +repo is empty with little information about content of the repo. #### New user content +- There is a 'Getting started' section on the website but it contains information about other features. + +- The documentation repo does not have a contributor guide for new users + +- There isin't any documentation labeled 'Installation guide'. Instead, Installation instructions are part of a larger document labelled The Upadte Framework specification (latest) + +- TUF docs do not provide information about application-specific/OS functionality in system updates. Instead it states that TUF provides a secure way for applications to obtain and verify files being distributed by trusted parties. + +- There is sample code in the content that can be easily copy-pastable on other platforms. + + + + + + From ff59058c1eac8e87a598fbbf946bd10132748db5 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Thu, 20 Jun 2024 12:50:51 +0300 Subject: [PATCH 04/96] Finish analysis of the Project documentation section Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 83 +++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 5 deletions(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index 5e7b035..3a1d40e 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -140,28 +140,101 @@ documentation rubric. - Docs do not have tutorials for specific feature implementation. But, there are videos explaining various use cases. -- There are not specific task-based guides for features. The available guide for implementing the specification is part of a larger document labelled 'Specification latest' +- There are not specific task-based guides for features. The available guide for implementing the specification is part of a larger document labelled [Specification(latest)](https://theupdateframework.github.io/specification/latest) - There is a FAQ and reporting issues sections for troubleshooting. - There is a a well detailed API reference for multiple TUF APIs -- README on theupdateframework.io +- README on [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) repo is empty with little information about content of the repo. #### New user content -- There is a 'Getting started' section on the website but it contains information about other features. +- There is a 'Getting started' section on the website with information about main features. But there's repetition of content from other pages. For example the *Specification (latest)* and *index* include information present in the project and overview sections. This section is confusing for new users. -- The documentation repo does not have a contributor guide for new users +- The documentation repo does not have a contributor guide for new users to get started -- There isin't any documentation labeled 'Installation guide'. Instead, Installation instructions are part of a larger document labelled The Upadte Framework specification (latest) +- There isin't any documentation labeled 'Installation guide'. Instead, installation instructions are part of a larger document labelled [The Update Framework specification](https://theupdateframework.github.io/specification/latest) - TUF docs do not provide information about application-specific/OS functionality in system updates. Instead it states that TUF provides a secure way for applications to obtain and verify files being distributed by trusted parties. - There is sample code in the content that can be easily copy-pastable on other platforms. +- It's not clear that the documentation is up-to-date as there are no dates on docs or release notes published.The only document on the site with dates is the [Specification file](https://theupdateframework.github.io/specification/latest/) + +#### Content maintainability & site mechanics + +- The documentation is not searchable. You have to go through the site to find what you are looking for. + +- The Docs are managed through docs-as-code site Hugo and content written in markdown. However,it appears the updates are made manually. + + +#### Content creation processes + +- Documentation lacks contribution process guides and information on how to get started. + +- Documentation lacks procedures for duplicating the documentation locally. + +- It's not clear whether the code release process is synced with the documentation creation and updates. + +- It's not clear who reviews and approves documentation pull requests and updates either on the website or repo. + +- Information about TUF project maintainers is available on the website but not on the project documentation repo. + +#### Inclusive language + +- I noted one instance of use of non-recommended words as documented by the + [Inclusive Naming Initiative](https://inclusivenaming.org) website. The word *Aborted* is used in the [Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time) + +- There is no use of abliest language like simple,easy in the documentation. + + +### Recommendations + +#### Information architecture +- Information should be re-organized on the website to better the workflow. For example, each section should contain only related information. Consider the following: + - The **About section** should only have introductory information about the project in the following sequence. *Overview, History, Project and Publications, and Timeline*. The code of conduct moved to the Community section. + + - The **Getting Started** section should contain information on how to use the software or contribute to the project. That is:*Security,Roles and metadata,Implementations,Videos & Tutorials, and FAQs* The *The specification(latest) and index* should be removed because they are linked in the *Project page* + + - Include *Code of conduct* in the **Community section** + - The *Contribute* page should include information on various areas of contribution e.g The spec,Documentataion etc and not to a specific repo. This way users can easily find the areas of interest. + +- Provide step-by-step tutorials for each use case on a separate page and label it as such. At the moment all the tutorials are included in a larger document the *Specification(latest)* + +- Create a **README** on the documentation repo with information detailing the content of the repo. Also include a **contribution guide** and information of how to set up the website and run it locally for new contributors. You can include a getting started section on the README. + +#### New user content + +- Include only new user content in the **Getting started** Include information about features, tutorials and guides. Remove information about the Specification as it's repeated in the *Project section*. + +- Include a **README** in the documentation with a contributor guide on how to get started with Docs. + +- Create an *Installation guide* on a separate page. This can contain step-to-step instructions for diffent users including begginers. Installation instructions in the [The Update Framework specification](https://theupdateframework.github.io/specification/latest) can be included here. + +#### Content maintainability & site mechanics +- Include a search button on the website to make it easier for users to find content + + +#### Content creation processes + +- Provide information about the Docs website such as the tools used and how to set up ad run it locally. + +- Provide information on the contribution process including having contribution guides on the website and the documentaion repo. You can also include contribution guidelines to avoid violations. + +- Include dates on the documentation release on the website and the repo to inform users of their relevance. + +- Include information about verified maintainers on the documentation repo. It makes it easier for contributors to know who to contact for assistance. + +#### Inclusive language + +- Replace the word *Aborted* mentioned in the [Specification document](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) with recommended suggestions in the [Inclusive language documentation](https://inclusivenaming.org/word-lists/tier-1/abort/) + + + + From e48f0a210a7d73214bae1c90ea94783b3725b55b Mon Sep 17 00:00:00 2001 From: Dindihub Date: Thu, 20 Jun 2024 12:57:34 +0300 Subject: [PATCH 05/96] Correct rating on Criteria rubic Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index 3a1d40e..aa197c2 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -115,7 +115,7 @@ to legal requirements such as copyright and licensing issues. | Criteria | Rating (1-5) | | -------------------------- | -------------- | | Information architecture | 3 | -| New user content | 1 | +| New user content | 3 | | Content maintainability | 3 | | Content creation processes | 1 | | Inclusive language | 3 | From 38b4dad893c656668ec073b6da77dceade757cd1 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Thu, 20 Jun 2024 16:15:32 +0300 Subject: [PATCH 06/96] Add general comments to Project documentation analysis section Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 80 ++++++++++++++++++++++++++----- 1 file changed, 68 insertions(+), 12 deletions(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index aa197c2..9b81661 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -109,13 +109,13 @@ as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. -## Project documentation +## Project Documentation | Criteria | Rating (1-5) | | -------------------------- | -------------- | | Information architecture | 3 | -| New user content | 3 | +| New user content | 1 | | Content maintainability | 3 | | Content creation processes | 1 | | Inclusive language | 3 | @@ -127,11 +127,14 @@ Scale: - 5 = (Is executed extremely well or no improvement required) ### Comments -The following sections contain brief assessments of each element of the Project -documentation rubric. +- Information is repeated througout the site.For example the TUF Specification file has been referenced in more than one page. Also information in the Spec file is repeated on other pages of the website. Some pages can be consolidated into others. + +- The website content needs restructuring to align with it's use case. For example the information in the sections should be correspond with the label of the section i.e *About* should only contain introductory content about the project. + +- The information available for news users and contributors is not satisfactory. There are no step-to-step tutorials to guide news users to get started with the software, neither are there contributor guidelines. -#### Information architecture +#### Information architecture - There is an overview section explaining what TUF is and its use cases. The features, the metadata and roles are well explained with examples for each metadata. - Repetition of content on different pages makes content confusing @@ -151,7 +154,6 @@ repo is empty with little information about content of the repo. #### New user content - - There is a 'Getting started' section on the website with information about main features. But there's repetition of content from other pages. For example the *Specification (latest)* and *index* include information present in the project and overview sections. This section is confusing for new users. - The documentation repo does not have a contributor guide for new users to get started @@ -165,14 +167,12 @@ repo is empty with little information about content of the repo. - It's not clear that the documentation is up-to-date as there are no dates on docs or release notes published.The only document on the site with dates is the [Specification file](https://theupdateframework.github.io/specification/latest/) #### Content maintainability & site mechanics - - The documentation is not searchable. You have to go through the site to find what you are looking for. - The Docs are managed through docs-as-code site Hugo and content written in markdown. However,it appears the updates are made manually. #### Content creation processes - - Documentation lacks contribution process guides and information on how to get started. - Documentation lacks procedures for duplicating the documentation locally. @@ -184,7 +184,6 @@ repo is empty with little information about content of the repo. - Information about TUF project maintainers is available on the website but not on the project documentation repo. #### Inclusive language - - I noted one instance of use of non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website. The word *Aborted* is used in the [Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time) @@ -207,7 +206,6 @@ repo is empty with little information about content of the repo. - Create a **README** on the documentation repo with information detailing the content of the repo. Also include a **contribution guide** and information of how to set up the website and run it locally for new contributors. You can include a getting started section on the README. #### New user content - - Include only new user content in the **Getting started** Include information about features, tutorials and guides. Remove information about the Specification as it's repeated in the *Project section*. - Include a **README** in the documentation with a contributor guide on how to get started with Docs. @@ -217,9 +215,10 @@ repo is empty with little information about content of the repo. #### Content maintainability & site mechanics - Include a search button on the website to make it easier for users to find content +- The Docs repo should be the entry point of all repos. Meaning the Docs README shoould contain all the TUF project information including links to the other repos and contributor guidelines. -#### Content creation processes +#### Content creation processes - Provide information about the Docs website such as the tools used and how to set up ad run it locally. - Provide information on the contribution process including having contribution guides on the website and the documentaion repo. You can also include contribution guidelines to avoid violations. @@ -229,10 +228,67 @@ repo is empty with little information about content of the repo. - Include information about verified maintainers on the documentation repo. It makes it easier for contributors to know who to contact for assistance. #### Inclusive language - - Replace the word *Aborted* mentioned in the [Specification document](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) with recommended suggestions in the [Inclusive language documentation](https://inclusivenaming.org/word-lists/tier-1/abort/) +## Contributor Documentation + + +| Criteria | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | [rating (1-5)] | +| Beginner friendly issue backlog | [rating (1-5)] | +| “New contributor” getting started content | [rating (1-5)] | +| Project governance documentation | [rating (1-5)] | + +- 1 = (Is not present or requires significant work) +- 3 = (Is present, but needs work) +- 5 = (Is executed extremely well or no improvement required) + +### Comments +The following sections contain brief assessments of each element of the +Contributor Documentation rubric. + +#### Communication methods documented +- Information about the TUF **slack channel** is available on the website on both the Community and Contact sections. However,this information should be visible on the doc repo README for easy access. + +- The repo link on the website does not point to the documentation but rather the [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file) + +- Information about the mailing list is included in the documentation. There's no information about project meetings. Instead the users are directed to join the #TUF channel on CNCF slack. + +#### Beginner friendly issue backlog +- Issues on the docs repo are missing labels, making it hard for contributors to identify 'Docs' issues. +- New contributors will have a hard time getting started as none of the issues are marked "good first issue” label" +- Most issues on the docs repo have a title and a detailed description. +- Issues are not maintained for staleness. There are issues opened in 2021 that are still open with the information on their status. + +#### New contributor getting started content + +- Do you have a community repository or section on your website? +- Is there a document specifically for new contributors/your first contribution? +- Do new users know where to get help? + +#### Project governance documentation + +One of the CNCF’s core project values is open governance. + +We evaluate on the following: + +- Is project governance clearly documented? + +### Recommendations + +> AUTHOR NOTE: Write general recommendations based on the comments from the +> previous section. + +#### Communication methods documented + +#### Beginner friendly issue backlog + +#### New contributor getting started content + +#### Project governance documentation + From 67306a57e376a64c17691f38bb39e8f0f7ad7094 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Thu, 20 Jun 2024 17:11:02 +0300 Subject: [PATCH 07/96] Analysis and recommendations of the Contributor documentation section Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 52 +++++++++++++++---------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index 9b81661..aa891c2 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -126,7 +126,7 @@ Scale: - 3 = (Is present, but needs improvement) - 5 = (Is executed extremely well or no improvement required) -### Comments +### Summary of issues - Information is repeated througout the site.For example the TUF Specification file has been referenced in more than one page. Also information in the Spec file is repeated on other pages of the website. Some pages can be consolidated into others. - The website content needs restructuring to align with it's use case. For example the information in the sections should be correspond with the label of the section i.e *About* should only contain introductory content about the project. @@ -236,18 +236,23 @@ repo is empty with little information about content of the repo. | Criteria | [Rating (1-5)] | | ----------------------------------------- | -------------- | -| Communication methods documented | [rating (1-5)] | -| Beginner friendly issue backlog | [rating (1-5)] | -| “New contributor” getting started content | [rating (1-5)] | -| Project governance documentation | [rating (1-5)] | +| Communication methods documented | 3 | +| Beginner friendly issue backlog | 1 | +| “New contributor” getting started content | 1 | +| Project governance documentation | 3 | + +Scale: - 1 = (Is not present or requires significant work) - 3 = (Is present, but needs work) - 5 = (Is executed extremely well or no improvement required) -### Comments -The following sections contain brief assessments of each element of the -Contributor Documentation rubric. +### Summary of Issues +- The documentation does not contain information tailored to contributors +- Information about TUF communication channels is not visible in the docs repo. But the information is available on the website. +- The documentation does not contain information about other project repos and their links. Making it harder for contributors to find them. +- The documentation repo issues do not appear to be maintained. There are old issues that are still open which may confuse contributors on what to work on. +- Issues do not have labels making it hard for contributors to identify suitable areas of interest #### Communication methods documented - Information about the TUF **slack channel** is available on the website on both the Community and Contact sections. However,this information should be visible on the doc repo README for easy access. @@ -258,39 +263,34 @@ Contributor Documentation rubric. #### Beginner friendly issue backlog - Issues on the docs repo are missing labels, making it hard for contributors to identify 'Docs' issues. -- New contributors will have a hard time getting started as none of the issues are marked "good first issue” label" +- New contributors have a hard time getting started as none of the issues are marked "good first issue” label" - Most issues on the docs repo have a title and a detailed description. - Issues are not maintained for staleness. There are issues opened in 2021 that are still open with the information on their status. #### New contributor getting started content - -- Do you have a community repository or section on your website? -- Is there a document specifically for new contributors/your first contribution? -- Do new users know where to get help? +- There's a community section on the website +- No specific documentation for new users of the software on the website or the docs repo. +- The docs provide several channels for reporting issues, contacting the maintainers and slack community. #### Project governance documentation - -One of the CNCF’s core project values is open governance. - -We evaluate on the following: - -- Is project governance clearly documented? +- The project governance is documented on the website. There's sufficient informtaion about it's history including leaders,maintainers and contributors. However, this information is not visisble in the docs repo README. ### Recommendations -> AUTHOR NOTE: Write general recommendations based on the comments from the -> previous section. - #### Communication methods documented - +- The documentation repo link should be included on the site as an entry point for the project. The repo can then include information about ther repos. +- Include communication channels on the Docs repo README for visibility. +- Provide information about project meetings e.g a meeting link and calendar. #### Beginner friendly issue backlog - +- Maintain issues, track,close and stale old issues to reduce backlog. +- Label all issues to assist new users and contributors identify areas of interest. #### New contributor getting started content - +- Include instructions on how to contribute on a CONTRIBUTING guideline e.g how to identify issues,forking,cloning, and submitting PRs. #### Project governance documentation +- Information on project governance is well documented on the website. However, the same need to be included in the docs repo. - +## Website and infrastructure From 164d6931cbb7bd143a932de764a81f4822869c63 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Fri, 21 Jun 2024 16:13:13 +0300 Subject: [PATCH 08/96] Correct Typos on Docs Project documentation section Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 46 +++++++++++++++---------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index aa891c2..c1c46f3 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -127,11 +127,11 @@ Scale: - 5 = (Is executed extremely well or no improvement required) ### Summary of issues -- Information is repeated througout the site.For example the TUF Specification file has been referenced in more than one page. Also information in the Spec file is repeated on other pages of the website. Some pages can be consolidated into others. +- Information is repeated throughout the site.For example the TUF Specification file has been referenced in more than one page.Some pages can be consolidated into others. -- The website content needs restructuring to align with it's use case. For example the information in the sections should be correspond with the label of the section i.e *About* should only contain introductory content about the project. +- The website content needs restructuring to align sections with sub-sections related to their use case. For example, information in the sections should be correspond with the label of the section i.e *About* should only contain introductory content about the project. -- The information available for news users and contributors is not satisfactory. There are no step-to-step tutorials to guide news users to get started with the software, neither are there contributor guidelines. +- The information available for news users and contributors is not satisfactory. There are no step-to-step guides and tutorials for new users to get started with the software, neither are there contributor guidelines. #### Information architecture @@ -160,11 +160,11 @@ repo is empty with little information about content of the repo. - There isin't any documentation labeled 'Installation guide'. Instead, installation instructions are part of a larger document labelled [The Update Framework specification](https://theupdateframework.github.io/specification/latest) -- TUF docs do not provide information about application-specific/OS functionality in system updates. Instead it states that TUF provides a secure way for applications to obtain and verify files being distributed by trusted parties. +- TUF docs do not provide information about application-specific/OS functionality in system updates. Instead the documentation states that TUF provides a secure way for applications to obtain and verify files being distributed by trusted parties. -- There is sample code in the content that can be easily copy-pastable on other platforms. +- There is sample code in the content that can be easily copy-pasted on other platforms. -- It's not clear that the documentation is up-to-date as there are no dates on docs or release notes published.The only document on the site with dates is the [Specification file](https://theupdateframework.github.io/specification/latest/) +- It's not clear whether the documentation is up-to-date as there are no dates on docs or release notes published.The only document on the site with dates is the [Specification file](https://theupdateframework.github.io/specification/latest/) #### Content maintainability & site mechanics - The documentation is not searchable. You have to go through the site to find what you are looking for. @@ -194,12 +194,12 @@ repo is empty with little information about content of the repo. #### Information architecture - Information should be re-organized on the website to better the workflow. For example, each section should contain only related information. Consider the following: - - The **About section** should only have introductory information about the project in the following sequence. *Overview, History, Project and Publications, and Timeline*. The code of conduct moved to the Community section. + - The **About section** should only have introductory information about the project in the following sequence. *Overview, History, Project and Publications, and Timeline*. The *code of conduct* should be moved to the Community section. - - The **Getting Started** section should contain information on how to use the software or contribute to the project. That is:*Security,Roles and metadata,Implementations,Videos & Tutorials, and FAQs* The *The specification(latest) and index* should be removed because they are linked in the *Project page* + - The **Getting Started** section should contain information on how to use the software or contribute to the project. Consider the following sequence for this section:*Security,Roles and metadata,Implementations,Videos & Tutorials, and FAQs*. The *specification(latest) and index* should be removed because they are linked in the *Project page* - Include *Code of conduct* in the **Community section** - - The *Contribute* page should include information on various areas of contribution e.g The spec,Documentataion etc and not to a specific repo. This way users can easily find the areas of interest. + - The *Contribute* page should include information of various areas of contribution e.g The spec, repos etc and not to a specific repo. This way users can easily find the areas of interest. - Provide step-by-step tutorials for each use case on a separate page and label it as such. At the moment all the tutorials are included in a larger document the *Specification(latest)* @@ -208,22 +208,22 @@ repo is empty with little information about content of the repo. #### New user content - Include only new user content in the **Getting started** Include information about features, tutorials and guides. Remove information about the Specification as it's repeated in the *Project section*. -- Include a **README** in the documentation with a contributor guide on how to get started with Docs. +- Include a **README** in the documentation repo with a contributor guide on how to get started with Docs. -- Create an *Installation guide* on a separate page. This can contain step-to-step instructions for diffent users including begginers. Installation instructions in the [The Update Framework specification](https://theupdateframework.github.io/specification/latest) can be included here. +- Create an *Installation guide* on a separate page. This can contain step-to-step instructions for diffent users including beginners. Installation instructions in the [The Update Framework specification](https://theupdateframework.github.io/specification/latest) can be included here. #### Content maintainability & site mechanics -- Include a search button on the website to make it easier for users to find content +- Include a search button on the website to make it easier for users to search and find content. -- The Docs repo should be the entry point of all repos. Meaning the Docs README shoould contain all the TUF project information including links to the other repos and contributor guidelines. +- The Docs repo should be the entry point of all repos. Meaning, the Docs README should contain all the TUF project information including links to the other repos and contributor guidelines. #### Content creation processes - Provide information about the Docs website such as the tools used and how to set up ad run it locally. -- Provide information on the contribution process including having contribution guides on the website and the documentaion repo. You can also include contribution guidelines to avoid violations. +- Provide information about the contribution process including having contribution guides on the website and the documentation repo. You can also include contribution guidelines to avoid violations. -- Include dates on the documentation release on the website and the repo to inform users of their relevance. +- Include dates on the documentation on the website and the repo to inform users of their relevance. - Include information about verified maintainers on the documentation repo. It makes it easier for contributors to know who to contact for assistance. @@ -248,10 +248,10 @@ Scale: - 5 = (Is executed extremely well or no improvement required) ### Summary of Issues -- The documentation does not contain information tailored to contributors +- The documentation does not contain information tailored to contributors. - Information about TUF communication channels is not visible in the docs repo. But the information is available on the website. - The documentation does not contain information about other project repos and their links. Making it harder for contributors to find them. -- The documentation repo issues do not appear to be maintained. There are old issues that are still open which may confuse contributors on what to work on. +- The documentation repo issues do not appear to be maintained. There are old issues that are still open which may confuse contributors looking for issues to work on. - Issues do not have labels making it hard for contributors to identify suitable areas of interest #### Communication methods documented @@ -268,17 +268,17 @@ Scale: - Issues are not maintained for staleness. There are issues opened in 2021 that are still open with the information on their status. #### New contributor getting started content -- There's a community section on the website -- No specific documentation for new users of the software on the website or the docs repo. -- The docs provide several channels for reporting issues, contacting the maintainers and slack community. +- There's a community section on the website with information on how to join the community. +- No specific documentation tailored for new users to get started the software on the website or the docs repo. +- The docs provide several channels for reporting issues, contacting the maintainers, and slack community. #### Project governance documentation -- The project governance is documented on the website. There's sufficient informtaion about it's history including leaders,maintainers and contributors. However, this information is not visisble in the docs repo README. +- The project governance is well documented on the website. There's sufficient informtaion about it's history including leaders,maintainers and contributors. However, this information is not visisble in the docs repo README. ### Recommendations #### Communication methods documented -- The documentation repo link should be included on the site as an entry point for the project. The repo can then include information about ther repos. +- The documentation repo link should be included on the site as an entry point for the project. The repo can then include information about other repos. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings e.g a meeting link and calendar. #### Beginner friendly issue backlog @@ -287,7 +287,7 @@ Scale: #### New contributor getting started content - Include instructions on how to contribute on a CONTRIBUTING guideline e.g how to identify issues,forking,cloning, and submitting PRs. #### Project governance documentation -- Information on project governance is well documented on the website. However, the same need to be included in the docs repo. +- Information on project governance is well documented on the website. However, the same needs to be included in the docs repo on GitHub. ## Website and infrastructure From b40721fc66c7a5bc217a359c0aaaaba57ec7b249 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Sat, 22 Jun 2024 16:27:54 +0300 Subject: [PATCH 09/96] Website and infrastructure section analysis Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 128 +++++++++++++++++++++++++++--- 1 file changed, 116 insertions(+), 12 deletions(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index c1c46f3..0cd5f47 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -122,14 +122,20 @@ to legal requirements such as copyright and licensing issues. Scale: -- 1 = (Is not present) -- 3 = (Is present, but needs improvement) -- 5 = (Is executed extremely well or no improvement required) +1 = Not present + +2 = Needs improvement + +3 = Meets standards + +4 = Meets or exceeds standards + +5 = Exemplary ### Summary of issues -- Information is repeated throughout the site.For example the TUF Specification file has been referenced in more than one page.Some pages can be consolidated into others. +- Information is repeated throughout the site. For example the TUF Specification file has been referenced in more than one page. Some pages can be consolidated into others. -- The website content needs restructuring to align sections with sub-sections related to their use case. For example, information in the sections should be correspond with the label of the section i.e *About* should only contain introductory content about the project. +- The website content needs restructuring to align sections with sub-sections related to their use case. For example, information in the sections should correspond with the label of the section i.e *About* should only contain introductory content about the project. - The information available for news users and contributors is not satisfactory. There are no step-to-step guides and tutorials for new users to get started with the software, neither are there contributor guidelines. @@ -194,12 +200,12 @@ repo is empty with little information about content of the repo. #### Information architecture - Information should be re-organized on the website to better the workflow. For example, each section should contain only related information. Consider the following: - - The **About section** should only have introductory information about the project in the following sequence. *Overview, History, Project and Publications, and Timeline*. The *code of conduct* should be moved to the Community section. + - The **About section** should only have introductory information about the project in the following sequence. *Overview, History, Project and Publications, and Timeline*. The *Code of conduct* should be moved to the Community section. - - The **Getting Started** section should contain information on how to use the software or contribute to the project. Consider the following sequence for this section:*Security,Roles and metadata,Implementations,Videos & Tutorials, and FAQs*. The *specification(latest) and index* should be removed because they are linked in the *Project page* + - The **Getting Started** section should contain information on how to use the software or contribute to the project. Consider the following sequence for this section:*Security,Roles and metadata,Implementations,Videos & Tutorials, and FAQs*. The *specification(latest) and Specification index* pages should be removed because they are linked in the *Project page* - Include *Code of conduct* in the **Community section** - - The *Contribute* page should include information of various areas of contribution e.g The spec, repos etc and not to a specific repo. This way users can easily find the areas of interest. + - The *Contribute* page should include information of various areas of contribution e.g The spec, repos etc and not to a specific repo. This way users can easily find areas of interest. - Provide step-by-step tutorials for each use case on a separate page and label it as such. At the moment all the tutorials are included in a larger document the *Specification(latest)* @@ -243,9 +249,15 @@ repo is empty with little information about content of the repo. Scale: -- 1 = (Is not present or requires significant work) -- 3 = (Is present, but needs work) -- 5 = (Is executed extremely well or no improvement required) +1 = Not present + +2 = Needs improvement + +3 = Meets standards + +4 = Meets or exceeds standards + +5 = Exemplary ### Summary of Issues - The documentation does not contain information tailored to contributors. @@ -263,7 +275,7 @@ Scale: #### Beginner friendly issue backlog - Issues on the docs repo are missing labels, making it hard for contributors to identify 'Docs' issues. -- New contributors have a hard time getting started as none of the issues are marked "good first issue” label" +- New contributors will have a hard time getting started as none of the issues are marked "good first issue” label - Most issues on the docs repo have a title and a detailed description. - Issues are not maintained for staleness. There are issues opened in 2021 that are still open with the information on their status. @@ -292,6 +304,98 @@ Scale: ## Website and infrastructure +| Criteria | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | 4 | +| Meets min website req. (for maturity level) | 3 | +| Usability, accessibility, and design | 3 | +| Branding and design | 4 | +| Case studies/social proof | 5 | +| SEO, Analytics, and site-local search | 2 | +| Maintenance planning | 2 | +| A11y plan & implementation | 3 | +| Mobile-first plan & impl. | 5 | +| HTTPS access & HTTP redirect | 5 | +| Google Analytics 4 for production only | 1 | +| Indexing allowed for production server only | 1 | +| Intra-site / local search | 1 | +| Account custodians are documented | 3 | + +Scale: + +1 = Not present + +2 = Needs improvement + +3 = Meets standards + +4 = Meets or exceeds standards + +5 = Exemplary + + +### Summary of Issues +- The website repo is named *theupdateframework.io* which makes it harder to identify it. Name it according to it's content. +- There's no guideline or tutorial to assist users to generate the website from the website repo. +- Alot of empty space between the Hero section and the Navbar. Due to this spacing, information is pushed out of eyelevel. You have to scroll down to find it. +- The available [TUF blog](https://theupdateframework.github.io/python-tuf/) page is not available on the website. It's hosted on GitHub. +- Information about the website build, tools and how to generate it are not available on the website or the docs repo. +- Intra-site search mechanism is not available from the website. The only naviagation option is a menu bar. This makes it difficult to find information. + +#### Single-source requirement +- All source files are in the website repo named [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) + +#### Minimal website requirements +The website docs analysis is in progess. + +#### Usability, accessibility and devices +- The website follows a mobile-first design with all pages, menu's and features visible on smaller screens. +- Website pages are readable +- The website does not provide a text-to-speech option for users. + +#### Branding and design +- There's a recognizable brand for the project , a logo and blue-white color scheme used througout the website. +- The website design is good and suitable for reading. However, consider reducing space between the hero section and the Navbar. + +#### Case studies/social proof +- There are case studies documented on the website under the *Adoptions* page. +- There's a logo wall of users or participating organizations documented in the *Adoptions* page. +- No avaliable community talks on the website. They have however provided links to the community channel. +- The available [TUF blog](https://theupdateframework.github.io/python-tuf/) page is not available on the website. It's hosted on GitHub + +#### SEO, Analytics and site-local search +- It's not clear what analytics are used on the site +- Intra-site search is not available from the website +- There's no mention of custodians of analytics and search. + +#### Maintenance planning +- The Website runs on Hugo and supported by +the community. +- It's not clear who are the maintainers of the website. + + +#### Other +- The website is accessible via HTTPS + +### Recommendations + +#### Single-source requirement +- Rename the The website repo *theupdateframework.io* to a name that reflect it's content e.g *TUFwebsite.io*. It makes it easier to find. + +#### Branding and design +- Reduce empty space between hero section and Navbar to bring information to eyelevel. At the moment the information is too far down, you have to scroll to find it. + +#### SEO, Analytics and site-local search +- Provide intra-site search options such as a search button to make it easier for users to search and find information. + +#### Case studies/social proof +- Add the [TUF blog](https://theupdateframework.github.io/python-tuf/) to the website. + +#### Maintenance planning +- Identify website maintainers on the site and their roles so users know who to contact in case issues arise. +- Provide information about the website build and how to generate on the docs repo. + + From a239b920eda7b53c2ce8e43cc1806b2a888aa9b4 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Tue, 25 Jun 2024 15:43:45 +0300 Subject: [PATCH 10/96] Add implementation strategy to implementation file Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-Implementation.md | 105 ++++++++++++++++++++++++ analyses/0012-TUF/TUF-analysis.md | 2 +- 2 files changed, 106 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/TUF-Implementation.md b/analyses/0012-TUF/TUF-Implementation.md index e69de29..8904679 100644 --- a/analyses/0012-TUF/TUF-Implementation.md +++ b/analyses/0012-TUF/TUF-Implementation.md @@ -0,0 +1,105 @@ +--- +title: Implementing TUF Doc Improvements +tags: TUF +--- + + +## Introduction + +This document provides actionable suggestions for improving the **theUpdateframework (TUF)** +technical documentation. + +For an analysis and general discussion of recommendations on TUF technical +documentation, see [TUF-analysis.md](TUF-analysis.md). + +### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards and +suggests possible improvements. In most cases there is more than one way to do +things. Few recommendations here are meant to be prescriptive. Rather, +recommendations are based on documentation best practices as understood by the +reviewers. The recommended implementations represent the reviewers' experience +with how to apply those best practices. In other words, borrowing terminology +from the lexicon of [RFCs][rfc-keywords], the changes described here should be +understood as "recommended" or "should" at the strongest, and "optional" or +"may" in many cases. Any "must" or "required" actions are clearly denoted as +such, and pertain to legal requirements such as copyright and licensing issues. + +The top-level documentation recommendations for this project are: +- **Reorganize documentation** + - Align sub-sections with related sections + - Consolidate some pages into others to avoid repetition + - Add user roles to the 'Getting started' documentation + - Add a section for instructional material to website and repo documentation to make it easier to find. It can be a sub-section under 'Getting started' + +- **Introduce instructional documentation** + - Identify TUF user roles (personas) + - Develop task-based material i.e How-tos for user roles + - Document TUF installation procedures in a separate page(At the moment it's in the spec doc) + - Develop quick start and contribution guides for new users + +- **Content maintanability and creation process** + - Rename the docs repo to a recognizable name e.g *TUF-ReadTheDocs* or similar + - Add search functionality to website to make it easier to find content + - Identify maintainers for the docs repo + - Add labels to the docs repo + - Add a README to the docs repo with information about the project including links to important project repos + - Develop a contributors' guideline for new users + - Create procedure for developing the docs site locally + - Include communication channels on the Docs repo README + - Provide information about project meetings e.g a meeting link and calendar on both the website and repo + - Add the [TUF blog](https://theupdateframework.github.io/python-tuf/) to the website. + +## Implementation + +## Reorganize documentation + +### Align sub-sections with related sections +Some sections listed on the menu bar have unrelated sub-sections. This structure makes information hard to find and can be confusing to new users. + I propose the following Navbar outline. This structure includes the user roles in the documentation. +- **About**: + - Overview + - History + - Project + - Publications + - Timeline +- **Getting started**: + - TUF security + - TUF specification(Roles and metadata,tutorials,videos etc) + - TUF proposals(linked to tutorials,videos) + - TUF implementation/Developers (linked to tutorials,videos) + - TUF docs(Link docs repo) + - Media(Videos and pictures of TUF events and seminars) + - FAQ +- **Community**: + - Adoptions + - Reporting issues + - Security audits + - Contribute-TAP, Docs + - Chat(CNCF slack) + - Code of conduct +- **News**: +- **Contact**: + - CNCF slack, meeting links or calendar + +### Consolidate some pages +The specification index has been reference three times on the site despite having its own sub-section. + +I propose that it remains in the project sub-section section under specification. But it be removed from the *Getting started* section. + +### Add user roles to Getting started section +Structure the *Getting started* section according to user roles. See the proposed *Getting started* above. The percieved user roles for this project are: + - **TUF specification**: Uses TUF metadata to download and verify targets + - **TUF proposals contributor** : Proposes major changes to the specification, including new features made as TUF Augmentation Proposals (TAPs) + - **TUF implementation/Developers** : Develops software with the TUF Python reference implementation + - **TUF docs**: Contributes to documentation + +Each role should have accompanying documentation and instructional material/tutorial to help users set up and start using TUF. + +## Introduce Instructional Material + +### Issue 1 + +### Issue 2 + +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index 0cd5f47..e4d0273 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -337,10 +337,10 @@ Scale: ### Summary of Issues - The website repo is named *theupdateframework.io* which makes it harder to identify it. Name it according to it's content. - There's no guideline or tutorial to assist users to generate the website from the website repo. -- Alot of empty space between the Hero section and the Navbar. Due to this spacing, information is pushed out of eyelevel. You have to scroll down to find it. - The available [TUF blog](https://theupdateframework.github.io/python-tuf/) page is not available on the website. It's hosted on GitHub. - Information about the website build, tools and how to generate it are not available on the website or the docs repo. - Intra-site search mechanism is not available from the website. The only naviagation option is a menu bar. This makes it difficult to find information. +- Alot of empty space between the Hero section and the Navbar. Due to this spacing, information is pushed out of eyelevel. You have to scroll down to find it. #### Single-source requirement - All source files are in the website repo named [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) From f15b7b419368f9ddaf5bb1dfb5cfa5485d5932da Mon Sep 17 00:00:00 2001 From: Dindihub Date: Wed, 26 Jun 2024 15:36:38 +0300 Subject: [PATCH 11/96] Finish the implementation guide Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-Implementation.md | 57 +++++++++++++++++++------ 1 file changed, 44 insertions(+), 13 deletions(-) diff --git a/analyses/0012-TUF/TUF-Implementation.md b/analyses/0012-TUF/TUF-Implementation.md index 8904679..0d1567c 100644 --- a/analyses/0012-TUF/TUF-Implementation.md +++ b/analyses/0012-TUF/TUF-Implementation.md @@ -56,7 +56,7 @@ The top-level documentation recommendations for this project are: ### Align sub-sections with related sections Some sections listed on the menu bar have unrelated sub-sections. This structure makes information hard to find and can be confusing to new users. - I propose the following Navbar outline. This structure includes the user roles in the documentation. + I propose the following Navbar outline which includes the user roles. - **About**: - Overview - History @@ -65,30 +65,32 @@ Some sections listed on the menu bar have unrelated sub-sections. This structure - Timeline - **Getting started**: - TUF security - - TUF specification(Roles and metadata,tutorials,videos etc) - - TUF proposals(linked to tutorials,videos) + - TUF specification (Roles and metadata,tutorials) + - TUF proposals (linked to tutorials,videos) - TUF implementation/Developers (linked to tutorials,videos) - - TUF docs(Link docs repo) - - Media(Videos and pictures of TUF events and seminars) + - TUF docs (Link docs repo) - FAQ - **Community**: - Adoptions - Reporting issues - Security audits - - Contribute-TAP, Docs - - Chat(CNCF slack) + - Contribute : TAP, Docs + - Chat (CNCF slack) - Code of conduct -- **News**: +- **Resources**: + - Blog + - News + - Videos - **Contact**: - CNCF slack, meeting links or calendar ### Consolidate some pages -The specification index has been reference three times on the site despite having its own sub-section. +The specification index has been referenced several times on the website despite having its own sub-section. -I propose that it remains in the project sub-section section under specification. But it be removed from the *Getting started* section. +I suggest that it remains in the project sub-section section under specification. But it be removed from the *Getting started* section. ### Add user roles to Getting started section -Structure the *Getting started* section according to user roles. See the proposed *Getting started* above. The percieved user roles for this project are: +Structure the *Getting started* section according to user roles. See the suggested *Getting started* above. The percieved user roles for this project are: - **TUF specification**: Uses TUF metadata to download and verify targets - **TUF proposals contributor** : Proposes major changes to the specification, including new features made as TUF Augmentation Proposals (TAPs) - **TUF implementation/Developers** : Develops software with the TUF Python reference implementation @@ -98,8 +100,37 @@ Each role should have accompanying documentation and instructional material/tuto ## Introduce Instructional Material -### Issue 1 +- Clearly identify user roles in the documentation and what can be achieved by each +- Create instructional material in the *Getting started* section for each user role i.e How-to guides and tutorials +- Document installation guides for each user role in a separate page. At the moment all the information for [TUF Specification](https://theupdateframework.github.io/specification/latest/) file. +- Include links to the github repos associated with the role. -### Issue 2 +## Content maintainability and creation process + +### Rename the docs Github repo + Rename the docs repo to a recognizable name e.g *TUF-ReadTheDocs* or similar to make it easier to find. At the moment, the repo is named *theupdateframework.io* which is too broad as it only contains docs and not all information about TUF projects + +### Add README to docs repo +Add a README to the docs repo with information about the project. I suggest the following information: Overview of the project, components, project repos, communication channels and links a contributors' guide. + +### Add search functionality to website +Consider adding a search functionality to website to make it easier for users to do intra-site searching. Hugo does not have such functionality so I advice using a plugin. +### Identify maintainers for docs repo +Identify maintainers for the docs repo both on the website and repo to make it easier for contributors to contact them. +### Add labels to the docs repo +Include labels to issues in the docs repo. These includes labels such as *#docs #Goodfirstissue* to make it easier for contributors to get started. + +### Develop a contributors' guideline for new users + Develop contributor guides to assist new contributors to get started. +### Create procedures for developing the docs site locally + Develop procedures for developing the docs site locally i.e cloning, building and serving the documentation. You can also provide information about the tools used to build and maintain the site. When such information is available it helps contributors know how to improve the website. You might get some good suggestions. + +### Provide project meeting links and calendar +Provide information about project meetings and a calendar on both the website and repo. Makes it easier for contributors to sinc with their calendars and get notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project have implemented this. + +### Include the TUF log to website + Add the [TUF blog](https://theupdateframework.github.io/python-tuf/) to the website. It has more visibility there than where it's located currently on the **Python/TUF repo** + + [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 From 52ae6d5f1cd7a520d3a60c4721a79871e45aa096 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Wed, 26 Jun 2024 15:58:26 +0300 Subject: [PATCH 12/96] correct typos in analysis file Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/TUF-analysis.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/TUF-analysis.md index e4d0273..86c1140 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/TUF-analysis.md @@ -133,7 +133,7 @@ Scale: 5 = Exemplary ### Summary of issues -- Information is repeated throughout the site. For example the TUF Specification file has been referenced in more than one page. Some pages can be consolidated into others. +- Information is repeated throughout the site. For example, the TUF Specification file has been referenced in more than one page. Some pages can be consolidated into others. - The website content needs restructuring to align sections with sub-sections related to their use case. For example, information in the sections should correspond with the label of the section i.e *About* should only contain introductory content about the project. @@ -141,7 +141,7 @@ Scale: #### Information architecture -- There is an overview section explaining what TUF is and its use cases. The features, the metadata and roles are well explained with examples for each metadata. +- There is an *overview* section explaining what TUF is and its use cases. The features, the metadata and roles are well explained with examples for each metadata. - Repetition of content on different pages makes content confusing @@ -160,7 +160,7 @@ repo is empty with little information about content of the repo. #### New user content -- There is a 'Getting started' section on the website with information about main features. But there's repetition of content from other pages. For example the *Specification (latest)* and *index* include information present in the project and overview sections. This section is confusing for new users. +- There is a *Getting started* section on the website with information about main features. But there's repetition of content from other pages. For example the *Specification (latest)* and *index* include information present in the project and overview sections. This section is confusing for new users. - The documentation repo does not have a contributor guide for new users to get started @@ -173,7 +173,7 @@ repo is empty with little information about content of the repo. - It's not clear whether the documentation is up-to-date as there are no dates on docs or release notes published.The only document on the site with dates is the [Specification file](https://theupdateframework.github.io/specification/latest/) #### Content maintainability & site mechanics -- The documentation is not searchable. You have to go through the site to find what you are looking for. +- The documentation is not searchable. You have to go through the site to find what you are looking for. The only source of naviagation is the menu bar. - The Docs are managed through docs-as-code site Hugo and content written in markdown. However,it appears the updates are made manually. From 7bf2c7514b2348166b32b07ab157d3b4de40cf6c Mon Sep 17 00:00:00 2001 From: Dindihub Date: Thu, 27 Jun 2024 10:36:34 +0300 Subject: [PATCH 13/96] Remove TUF prefix from file names and trailing slashes Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- .../0012-TUF/{TUF-analysis.md => analysis.md} | 20 +++++++++---------- ...UF-Implementation.md => implementation.md} | 10 +++++----- .../0012-TUF/{TUF-issues.md => issues.md} | 0 3 files changed, 15 insertions(+), 15 deletions(-) rename analyses/0012-TUF/{TUF-analysis.md => analysis.md} (96%) rename analyses/0012-TUF/{TUF-Implementation.md => implementation.md} (95%) rename analyses/0012-TUF/{TUF-issues.md => issues.md} (100%) diff --git a/analyses/0012-TUF/TUF-analysis.md b/analyses/0012-TUF/analysis.md similarity index 96% rename from analyses/0012-TUF/TUF-analysis.md rename to analyses/0012-TUF/analysis.md index 86c1140..c2881a2 100644 --- a/analyses/0012-TUF/TUF-analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -22,9 +22,9 @@ efforts. This document analyzes the current state of **The Update Framework (TUF)** documentation. It provides project leaders with an informed understanding -of potential problems in current project documentation. A second [TUF-impementation.md](./TUF-implementation.md) +of potential problems in current project documentation. A second [implementation](./implementation.md) document, , outlines an actionable plan for improvement. A third document, the -[TUF-issues.md](./TUF-issues.md) outlines issues to be added to the project documentation repository. These +[issues](./issues.md) outlines issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. This document: @@ -75,18 +75,18 @@ Each section begins with summary ratings based on a rubric with appropriate - **Recommendations**: Suggested changes that would improve the effectiveness of the documentation. -The accompanying [implementation](./TUF-implementation.md) document breaks the recommendations down into +The accompanying [implementation](./implementation.md) document breaks the recommendations down into concrete actions that can be implemented by project contributors. Its focus is on drilling down to specific, achievable work that can be completed in constrained blocks of time. Ultimately, the implementation items are decomposed -into a series of [issues](./TUF-issues.md) that can be implemented by the project maintainers. +into a series of [issues](./issues.md) that can be implemented by the project maintainers. ### How to use this document Readers interested only in actionable improvements should skip this document and -read the **[implementation](./TUF-implementation.md) plan** and **[issues](./TUF-issues.md) list**. +read the **[implementation](./implementation.md) plan** and **[issues](./issues.md) list**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining @@ -170,7 +170,7 @@ repo is empty with little information about content of the repo. - There is sample code in the content that can be easily copy-pasted on other platforms. -- It's not clear whether the documentation is up-to-date as there are no dates on docs or release notes published.The only document on the site with dates is the [Specification file](https://theupdateframework.github.io/specification/latest/) +- It's not clear whether the documentation is up-to-date as there are no dates on docs or release notes published.The only document on the site with dates is the [Specification file](https://theupdateframework.github.io/specification/latest) #### Content maintainability & site mechanics - The documentation is not searchable. You have to go through the site to find what you are looking for. The only source of naviagation is the menu bar. @@ -234,7 +234,7 @@ repo is empty with little information about content of the repo. - Include information about verified maintainers on the documentation repo. It makes it easier for contributors to know who to contact for assistance. #### Inclusive language -- Replace the word *Aborted* mentioned in the [Specification document](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) with recommended suggestions in the [Inclusive language documentation](https://inclusivenaming.org/word-lists/tier-1/abort/) +- Replace the word *Aborted* mentioned in the [Specification document](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) with recommended suggestions in the [Inclusive language documentation](https://inclusivenaming.org/word-lists/tier-1/abort) ## Contributor Documentation @@ -337,7 +337,7 @@ Scale: ### Summary of Issues - The website repo is named *theupdateframework.io* which makes it harder to identify it. Name it according to it's content. - There's no guideline or tutorial to assist users to generate the website from the website repo. -- The available [TUF blog](https://theupdateframework.github.io/python-tuf/) page is not available on the website. It's hosted on GitHub. +- The available [TUF blog](https://theupdateframework.github.io/python-tuf) page is not available on the website. It's hosted on GitHub. - Information about the website build, tools and how to generate it are not available on the website or the docs repo. - Intra-site search mechanism is not available from the website. The only naviagation option is a menu bar. This makes it difficult to find information. - Alot of empty space between the Hero section and the Navbar. Due to this spacing, information is pushed out of eyelevel. You have to scroll down to find it. @@ -361,7 +361,7 @@ The website docs analysis is in progess. - There are case studies documented on the website under the *Adoptions* page. - There's a logo wall of users or participating organizations documented in the *Adoptions* page. - No avaliable community talks on the website. They have however provided links to the community channel. -- The available [TUF blog](https://theupdateframework.github.io/python-tuf/) page is not available on the website. It's hosted on GitHub +- The available [TUF blog](https://theupdateframework.github.io/python-tuf) page is not available on the website. It's hosted on GitHub #### SEO, Analytics and site-local search - It's not clear what analytics are used on the site @@ -389,7 +389,7 @@ the community. - Provide intra-site search options such as a search button to make it easier for users to search and find information. #### Case studies/social proof -- Add the [TUF blog](https://theupdateframework.github.io/python-tuf/) to the website. +- Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the website. #### Maintenance planning - Identify website maintainers on the site and their roles so users know who to contact in case issues arise. diff --git a/analyses/0012-TUF/TUF-Implementation.md b/analyses/0012-TUF/implementation.md similarity index 95% rename from analyses/0012-TUF/TUF-Implementation.md rename to analyses/0012-TUF/implementation.md index 0d1567c..9569e78 100644 --- a/analyses/0012-TUF/TUF-Implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -10,7 +10,7 @@ This document provides actionable suggestions for improving the **theUpdateframe technical documentation. For an analysis and general discussion of recommendations on TUF technical -documentation, see [TUF-analysis.md](TUF-analysis.md). +documentation, see [analysis](./analysis.md). ### Recommendations, requirements, and best practices @@ -48,7 +48,7 @@ The top-level documentation recommendations for this project are: - Create procedure for developing the docs site locally - Include communication channels on the Docs repo README - Provide information about project meetings e.g a meeting link and calendar on both the website and repo - - Add the [TUF blog](https://theupdateframework.github.io/python-tuf/) to the website. + - Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the website. ## Implementation @@ -102,7 +102,7 @@ Each role should have accompanying documentation and instructional material/tuto - Clearly identify user roles in the documentation and what can be achieved by each - Create instructional material in the *Getting started* section for each user role i.e How-to guides and tutorials -- Document installation guides for each user role in a separate page. At the moment all the information for [TUF Specification](https://theupdateframework.github.io/specification/latest/) file. +- Document installation guides for each user role in a separate page. At the moment all the information for [TUF Specification](https://theupdateframework.github.io/specification/latest) file. - Include links to the github repos associated with the role. ## Content maintainability and creation process @@ -129,8 +129,8 @@ Include labels to issues in the docs repo. These includes labels such as *#docs Provide information about project meetings and a calendar on both the website and repo. Makes it easier for contributors to sinc with their calendars and get notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project have implemented this. ### Include the TUF log to website - Add the [TUF blog](https://theupdateframework.github.io/python-tuf/) to the website. It has more visibility there than where it's located currently on the **Python/TUF repo** + Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the website. It has more visibility there than where it's located currently on the **Python/TUF repo** -[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 + diff --git a/analyses/0012-TUF/TUF-issues.md b/analyses/0012-TUF/issues.md similarity index 100% rename from analyses/0012-TUF/TUF-issues.md rename to analyses/0012-TUF/issues.md From a1bd9a8782c62b2c1c6fbbc5ed64a6cbc0641e28 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Fri, 28 Jun 2024 11:44:26 +0300 Subject: [PATCH 14/96] Fix broken links Signed-off-by: Dindihub Signed-off-by: Patrice Chalin --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index c2881a2..93b64f8 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -44,7 +44,7 @@ repo. #### In scope - Website: https://theupdateframework.io -- Documentation: https://theupdateframework.io/content +- Documentation: https://theupdateframework.io - Website configuration(Hugo): https://github.com/theupdateframework/theupdateframework.io From 71e18b75a9471b9eb7748264f3645dd76a32a3b8 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 30 Jun 2024 19:26:39 -0400 Subject: [PATCH 15/96] Ran fix:format; fix markdown, copyedits Signed-off-by: Patrice Chalin --- analyses/0012-TUF/analysis.md | 411 +++++++++++++++++++--------- analyses/0012-TUF/implementation.md | 145 ++++++---- 2 files changed, 376 insertions(+), 180 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 93b64f8..8f3e524 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -6,12 +6,15 @@ modified: YYYY-MM-DD author: Sandra Dindi (@Dindihub) --- + + ## Introduction -This document analyzes the effectiveness and completeness of -[The Update Framework](https://theupdateframework.io) (TUF) open source software (OSS) project's documentation -and website. It is funded by the CNCF Foundation as part of its overall effort -to incubate, grow, and graduate open source cloud native software projects. +This document analyzes the effectiveness and completeness of +[The Update Framework](https://theupdateframework.io) (TUF) open source software +(OSS) project's documentation and website. It is funded by the CNCF Foundation +as part of its overall effort to incubate, grow, and graduate open source cloud +native software projects. According to CNCF best practices guidelines, effective documentation is a prerequisite for program graduation. The documentation analysis is the first @@ -21,11 +24,12 @@ efforts. ### Purpose This document analyzes the current state of **The Update Framework (TUF)** -documentation. It provides project leaders with an informed understanding -of potential problems in current project documentation. A second [implementation](./implementation.md) -document, , outlines an actionable plan for improvement. A third document, the -[issues](./issues.md) outlines issues to be added to the project documentation repository. These -issues can be taken up by contributors to improve the documentation. +documentation. It provides project leaders with an informed understanding of +potential problems in current project documentation. A second +[implementation](./implementation.md) document, , outlines an actionable plan +for improvement. A third document, the [issues](./issues.md) outlines issues to +be added to the project documentation repository. These issues can be taken up +by contributors to improve the documentation. This document: @@ -35,27 +39,32 @@ This document: ### Scope of analysis -The documentation includes the entire contents of the website, -the technical documentation, and documentation for contributors and users on the TUF GitHub repository. +The documentation includes the entire contents of the website, the technical +documentation, and documentation for contributors and users on the TUF GitHub +repository. -The TUF website and documentation are written in Markdown and compiled using the Hugo static site generator and served on the Netlify platform. The site's code is stored on the TUF GitHub -repo. +The TUF website and documentation are written in Markdown and compiled using the +Hugo static site generator and served on the Netlify platform. The site's code +is stored on the TUF GitHub repo. #### In scope -- Website: https://theupdateframework.io -- Documentation: https://theupdateframework.io -- Website configuration(Hugo): https://github.com/theupdateframework/theupdateframework.io - +- Website: +- Documentation: +- Website configuration(Hugo): + #### Out of scope -- The TUF community repository: https://github.com/theupdateframework/community -- TUF specification repository: https://github.com/theupdateframework/specification -- Python reference implementaion reposiroty: https://github.com/theupdateframework/python-tuf -- TUF Augmentation proposals respsitory: https://github.com/theupdateframework/taps -- TUF artwork repository: https://github.com/theupdateframework/artwork - +- The TUF community repository: + +- TUF specification repository: + +- Python reference implementation repository: + +- TUF Augmentation proposals repository: + +- TUF artwork repository: ### How this document is organized @@ -64,8 +73,10 @@ concern: - **Project documentation:** Analyzes documentation for users of the TUF project software. -- **Contributor documentation:** Analyzes documentation for existing and new contributors to TUF project. -- **Website:** Analyzes the mechanics of publishing the documentation, including branding, website structure, and maintainability. +- **Contributor documentation:** Analyzes documentation for existing and new + contributors to TUF project. +- **Website:** Analyzes the mechanics of publishing the documentation, including + branding, website structure, and maintainability. Each section begins with summary ratings based on a rubric with appropriate [criteria] for the section, then proceeds to: @@ -75,18 +86,19 @@ Each section begins with summary ratings based on a rubric with appropriate - **Recommendations**: Suggested changes that would improve the effectiveness of the documentation. -The accompanying [implementation](./implementation.md) document breaks the recommendations down into -concrete actions that can be implemented by project contributors. Its focus is -on drilling down to specific, achievable work that can be completed in -constrained blocks of time. +The accompanying [implementation](./implementation.md) document breaks the +recommendations down into concrete actions that can be implemented by project +contributors. Its focus is on drilling down to specific, achievable work that +can be completed in constrained blocks of time. -Ultimately, the implementation items are decomposed -into a series of [issues](./issues.md) that can be implemented by the project maintainers. +Ultimately, the implementation items are decomposed into a series of +[issues](./issues.md) that can be implemented by the project maintainers. ### How to use this document Readers interested only in actionable improvements should skip this document and -read the **[implementation](./implementation.md) plan** and **[issues](./issues.md) list**. +read the **[implementation](./implementation.md) plan** and +**[issues](./issues.md) list**. Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining @@ -96,7 +108,6 @@ to their area of concern: - [Contributor documentation]() - [Website and documentation infrastructure]() - #### Recommendations, requirements, and best practices This analysis measures documentation against CNCF project maturity standards, @@ -111,14 +122,13 @@ to legal requirements such as copyright and licensing issues. ## Project Documentation - -| Criteria | Rating (1-5) | -| -------------------------- | -------------- | -| Information architecture | 3 | -| New user content | 1 | -| Content maintainability | 3 | -| Content creation processes | 1 | -| Inclusive language | 3 | +| Criteria | Rating (1-5) | +| -------------------------- | ------------ | +| Information architecture | 3 | +| New user content | 1 | +| Content maintainability | 3 | +| Content creation processes | 1 | +| Inclusive language | 3 | Scale: @@ -133,114 +143,187 @@ Scale: 5 = Exemplary ### Summary of issues -- Information is repeated throughout the site. For example, the TUF Specification file has been referenced in more than one page. Some pages can be consolidated into others. -- The website content needs restructuring to align sections with sub-sections related to their use case. For example, information in the sections should correspond with the label of the section i.e *About* should only contain introductory content about the project. +- Information is repeated throughout the site. For example, the TUF + Specification file has been referenced in more than one page. Some pages can + be consolidated into others. -- The information available for news users and contributors is not satisfactory. There are no step-to-step guides and tutorials for new users to get started with the software, neither are there contributor guidelines. +- The website content needs restructuring to align sections with sub-sections + related to their use case. For example, information in the sections should + correspond with the label of the section i.e _About_ should only contain + introductory content about the project. +- The information available for news users and contributors is not satisfactory. + There are no step-to-step guides and tutorials for new users to get started + with the software, neither are there contributor guidelines. #### Information architecture -- There is an *overview* section explaining what TUF is and its use cases. The features, the metadata and roles are well explained with examples for each metadata. -- Repetition of content on different pages makes content confusing +- There is an _overview_ section explaining what TUF is and its use cases. The + features, the metadata and roles are well explained with examples for each + metadata. + +- Repetition of content on different pages makes content confusing -- Content needs to be re-organised to make it easier to follow +- Content needs to be re-organised to make it easier to follow -- Docs do not have tutorials for specific feature implementation. But, there are videos explaining various use cases. +- Docs do not have tutorials for specific feature implementation. But, there are + videos explaining various use cases. -- There are not specific task-based guides for features. The available guide for implementing the specification is part of a larger document labelled [Specification(latest)](https://theupdateframework.github.io/specification/latest) +- There are not specific task-based guides for features. The available guide for + implementing the specification is part of a larger document labelled + [Specification(latest)](https://theupdateframework.github.io/specification/latest) - There is a FAQ and reporting issues sections for troubleshooting. - There is a a well detailed API reference for multiple TUF APIs -- README on [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) -repo is empty with little information about content of the repo. - +- README on + [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) + repo is empty with little information about content of the repo. #### New user content -- There is a *Getting started* section on the website with information about main features. But there's repetition of content from other pages. For example the *Specification (latest)* and *index* include information present in the project and overview sections. This section is confusing for new users. -- The documentation repo does not have a contributor guide for new users to get started +- There is a _Getting started_ section on the website with information about + main features. But there's repetition of content from other pages. For example + the _Specification (latest)_ and _index_ include information present in the + project and overview sections. This section is confusing for new users. + +- The documentation repo does not have a contributor guide for new users to get + started -- There isin't any documentation labeled 'Installation guide'. Instead, installation instructions are part of a larger document labelled [The Update Framework specification](https://theupdateframework.github.io/specification/latest) +- There isin't any documentation labeled 'Installation guide'. Instead, + installation instructions are part of a larger document labelled + [The Update Framework specification](https://theupdateframework.github.io/specification/latest) -- TUF docs do not provide information about application-specific/OS functionality in system updates. Instead the documentation states that TUF provides a secure way for applications to obtain and verify files being distributed by trusted parties. +- TUF docs do not provide information about application-specific/OS + functionality in system updates. Instead the documentation states that TUF + provides a secure way for applications to obtain and verify files being + distributed by trusted parties. -- There is sample code in the content that can be easily copy-pasted on other platforms. +- There is sample code in the content that can be easily copy-pasted on other + platforms. -- It's not clear whether the documentation is up-to-date as there are no dates on docs or release notes published.The only document on the site with dates is the [Specification file](https://theupdateframework.github.io/specification/latest) +- It's not clear whether the documentation is up-to-date as there are no dates + on docs or release notes published.The only document on the site with dates is + the + [Specification file](https://theupdateframework.github.io/specification/latest) #### Content maintainability & site mechanics -- The documentation is not searchable. You have to go through the site to find what you are looking for. The only source of naviagation is the menu bar. -- The Docs are managed through docs-as-code site Hugo and content written in markdown. However,it appears the updates are made manually. +- The documentation is not searchable. You have to go through the site to find + what you are looking for. The only source of naviagation is the menu bar. +- The Docs are managed through docs-as-code site Hugo and content written in + markdown. However,it appears the updates are made manually. #### Content creation processes -- Documentation lacks contribution process guides and information on how to get started. + +- Documentation lacks contribution process guides and information on how to get + started. - Documentation lacks procedures for duplicating the documentation locally. -- It's not clear whether the code release process is synced with the documentation creation and updates. +- It's not clear whether the code release process is synced with the + documentation creation and updates. -- It's not clear who reviews and approves documentation pull requests and updates either on the website or repo. +- It's not clear who reviews and approves documentation pull requests and + updates either on the website or repo. -- Information about TUF project maintainers is available on the website but not on the project documentation repo. +- Information about TUF project maintainers is available on the website but not + on the project documentation repo. #### Inclusive language + - I noted one instance of use of non-recommended words as documented by the - [Inclusive Naming Initiative](https://inclusivenaming.org) website. The word *Aborted* is used in the [Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time) + [Inclusive Naming Initiative](https://inclusivenaming.org) website. The word + _Aborted_ is used in the + [Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time) - There is no use of abliest language like simple,easy in the documentation. - ### Recommendations #### Information architecture -- Information should be re-organized on the website to better the workflow. For example, each section should contain only related information. Consider the following: - - The **About section** should only have introductory information about the project in the following sequence. *Overview, History, Project and Publications, and Timeline*. The *Code of conduct* should be moved to the Community section. - - The **Getting Started** section should contain information on how to use the software or contribute to the project. Consider the following sequence for this section:*Security,Roles and metadata,Implementations,Videos & Tutorials, and FAQs*. The *specification(latest) and Specification index* pages should be removed because they are linked in the *Project page* +- Information should be re-organized on the website to better the workflow. For + example, each section should contain only related information. Consider the + following: + + - The **About section** should only have introductory information about the + project in the following sequence. _Overview, History, Project and + Publications, and Timeline_. The _Code of conduct_ should be moved to the + Community section. - - Include *Code of conduct* in the **Community section** - - The *Contribute* page should include information of various areas of contribution e.g The spec, repos etc and not to a specific repo. This way users can easily find areas of interest. + - The **Getting Started** section should contain information on how to use the + software or contribute to the project. Consider the following sequence for + this section:_Security,Roles and metadata,Implementations,Videos & + Tutorials, and FAQs_. The _specification(latest) and Specification index_ + pages should be removed because they are linked in the _Project page_ -- Provide step-by-step tutorials for each use case on a separate page and label it as such. At the moment all the tutorials are included in a larger document the *Specification(latest)* + - Include _Code of conduct_ in the **Community section** + - The _Contribute_ page should include information of various areas of + contribution e.g The spec, repos etc and not to a specific repo. This way + users can easily find areas of interest. -- Create a **README** on the documentation repo with information detailing the content of the repo. Also include a **contribution guide** and information of how to set up the website and run it locally for new contributors. You can include a getting started section on the README. +- Provide step-by-step tutorials for each use case on a separate page and label + it as such. At the moment all the tutorials are included in a larger document + the _Specification(latest)_ + +- Create a **README** on the documentation repo with information detailing the + content of the repo. Also include a **contribution guide** and information of + how to set up the website and run it locally for new contributors. You can + include a getting started section on the README. #### New user content -- Include only new user content in the **Getting started** Include information about features, tutorials and guides. Remove information about the Specification as it's repeated in the *Project section*. -- Include a **README** in the documentation repo with a contributor guide on how to get started with Docs. +- Include only new user content in the **Getting started** Include information + about features, tutorials and guides. Remove information about the + Specification as it's repeated in the _Project section_. + +- Include a **README** in the documentation repo with a contributor guide on how + to get started with Docs. -- Create an *Installation guide* on a separate page. This can contain step-to-step instructions for diffent users including beginners. Installation instructions in the [The Update Framework specification](https://theupdateframework.github.io/specification/latest) can be included here. +- Create an _Installation guide_ on a separate page. This can contain + step-to-step instructions for diffent users including beginners. Installation + instructions in the + [The Update Framework specification](https://theupdateframework.github.io/specification/latest) + can be included here. #### Content maintainability & site mechanics -- Include a search button on the website to make it easier for users to search and find content. -- The Docs repo should be the entry point of all repos. Meaning, the Docs README should contain all the TUF project information including links to the other repos and contributor guidelines. +- Include a search button on the website to make it easier for users to search + and find content. +- The Docs repo should be the entry point of all repos. Meaning, the Docs README + should contain all the TUF project information including links to the other + repos and contributor guidelines. #### Content creation processes -- Provide information about the Docs website such as the tools used and how to set up ad run it locally. -- Provide information about the contribution process including having contribution guides on the website and the documentation repo. You can also include contribution guidelines to avoid violations. +- Provide information about the Docs website such as the tools used and how to + set up ad run it locally. + +- Provide information about the contribution process including having + contribution guides on the website and the documentation repo. You can also + include contribution guidelines to avoid violations. -- Include dates on the documentation on the website and the repo to inform users of their relevance. +- Include dates on the documentation on the website and the repo to inform users + of their relevance. -- Include information about verified maintainers on the documentation repo. It makes it easier for contributors to know who to contact for assistance. +- Include information about verified maintainers on the documentation repo. It + makes it easier for contributors to know who to contact for assistance. #### Inclusive language -- Replace the word *Aborted* mentioned in the [Specification document](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) with recommended suggestions in the [Inclusive language documentation](https://inclusivenaming.org/word-lists/tier-1/abort) +- Replace the word _Aborted_ mentioned in the + [Specification document](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) + with recommended suggestions in the + [Inclusive language documentation](https://inclusivenaming.org/word-lists/tier-1/abort) ## Contributor Documentation - -| Criteria | [Rating (1-5)] | +| Criteria | [Rating (1-5)] | | ----------------------------------------- | -------------- | | Communication methods documented | 3 | | Beginner friendly issue backlog | 1 | @@ -260,51 +343,85 @@ Scale: 5 = Exemplary ### Summary of Issues -- The documentation does not contain information tailored to contributors. -- Information about TUF communication channels is not visible in the docs repo. But the information is available on the website. -- The documentation does not contain information about other project repos and their links. Making it harder for contributors to find them. -- The documentation repo issues do not appear to be maintained. There are old issues that are still open which may confuse contributors looking for issues to work on. -- Issues do not have labels making it hard for contributors to identify suitable areas of interest + +- The documentation does not contain information tailored to contributors. +- Information about TUF communication channels is not visible in the docs repo. + But the information is available on the website. +- The documentation does not contain information about other project repos and + their links. Making it harder for contributors to find them. +- The documentation repo issues do not appear to be maintained. There are old + issues that are still open which may confuse contributors looking for issues + to work on. +- Issues do not have labels making it hard for contributors to identify suitable + areas of interest #### Communication methods documented -- Information about the TUF **slack channel** is available on the website on both the Community and Contact sections. However,this information should be visible on the doc repo README for easy access. -- The repo link on the website does not point to the documentation but rather the [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file) +- Information about the TUF **slack channel** is available on the website on + both the Community and Contact sections. However,this information should be + visible on the doc repo README for easy access. + +- The repo link on the website does not point to the documentation but rather + the + [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file) -- Information about the mailing list is included in the documentation. There's no information about project meetings. Instead the users are directed to join the #TUF channel on CNCF slack. +- Information about the mailing list is included in the documentation. There's + no information about project meetings. Instead the users are directed to join + the #TUF channel on CNCF slack. #### Beginner friendly issue backlog -- Issues on the docs repo are missing labels, making it hard for contributors to identify 'Docs' issues. -- New contributors will have a hard time getting started as none of the issues are marked "good first issue” label + +- Issues on the docs repo are missing labels, making it hard for contributors to + identify 'Docs' issues. +- New contributors will have a hard time getting started as none of the issues + are marked "good first issue” label - Most issues on the docs repo have a title and a detailed description. -- Issues are not maintained for staleness. There are issues opened in 2021 that are still open with the information on their status. +- Issues are not maintained for staleness. There are issues opened in 2021 that + are still open with the information on their status. #### New contributor getting started content -- There's a community section on the website with information on how to join the community. -- No specific documentation tailored for new users to get started the software on the website or the docs repo. -- The docs provide several channels for reporting issues, contacting the maintainers, and slack community. + +- There's a community section on the website with information on how to join the + community. +- No specific documentation tailored for new users to get started the software + on the website or the docs repo. +- The docs provide several channels for reporting issues, contacting the + maintainers, and slack community. #### Project governance documentation -- The project governance is well documented on the website. There's sufficient informtaion about it's history including leaders,maintainers and contributors. However, this information is not visisble in the docs repo README. + +- The project governance is well documented on the website. There's sufficient + informtaion about it's history including leaders,maintainers and contributors. + However, this information is not visisble in the docs repo README. ### Recommendations #### Communication methods documented -- The documentation repo link should be included on the site as an entry point for the project. The repo can then include information about other repos. + +- The documentation repo link should be included on the site as an entry point + for the project. The repo can then include information about other repos. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings e.g a meeting link and calendar. + #### Beginner friendly issue backlog + - Maintain issues, track,close and stale old issues to reduce backlog. -- Label all issues to assist new users and contributors identify areas of interest. +- Label all issues to assist new users and contributors identify areas of + interest. + #### New contributor getting started content -- Include instructions on how to contribute on a CONTRIBUTING guideline e.g how to identify issues,forking,cloning, and submitting PRs. + +- Include instructions on how to contribute on a CONTRIBUTING guideline e.g how + to identify issues,forking,cloning, and submitting PRs. + #### Project governance documentation -- Information on project governance is well documented on the website. However, the same needs to be included in the docs repo on GitHub. +- Information on project governance is well documented on the website. However, + the same needs to be included in the docs repo on GitHub. ## Website and infrastructure -| Criteria | [Rating (1-5)] | +| Criteria | [Rating (1-5)] | | ------------------------------------------- | -------------- | | Single-source for all files | 4 | | Meets min website req. (for maturity level) | 3 | @@ -333,70 +450,98 @@ Scale: 5 = Exemplary - ### Summary of Issues -- The website repo is named *theupdateframework.io* which makes it harder to identify it. Name it according to it's content. -- There's no guideline or tutorial to assist users to generate the website from the website repo. -- The available [TUF blog](https://theupdateframework.github.io/python-tuf) page is not available on the website. It's hosted on GitHub. -- Information about the website build, tools and how to generate it are not available on the website or the docs repo. -- Intra-site search mechanism is not available from the website. The only naviagation option is a menu bar. This makes it difficult to find information. -- Alot of empty space between the Hero section and the Navbar. Due to this spacing, information is pushed out of eyelevel. You have to scroll down to find it. + +- The website repo is named _theupdateframework.io_ which makes it harder to + identify it. Name it according to it's content. +- There's no guideline or tutorial to assist users to generate the website from + the website repo. +- The available [TUF blog](https://theupdateframework.github.io/python-tuf) page + is not available on the website. It's hosted on GitHub. +- Information about the website build, tools and how to generate it are not + available on the website or the docs repo. +- Intra-site search mechanism is not available from the website. The only + naviagation option is a menu bar. This makes it difficult to find information. +- Alot of empty space between the Hero section and the Navbar. Due to this + spacing, information is pushed out of eyelevel. You have to scroll down to + find it. #### Single-source requirement -- All source files are in the website repo named [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) + +- All source files are in the website repo named + [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) #### Minimal website requirements + The website docs analysis is in progess. #### Usability, accessibility and devices -- The website follows a mobile-first design with all pages, menu's and features visible on smaller screens. + +- The website follows a mobile-first design with all pages, menu's and features + visible on smaller screens. - Website pages are readable - The website does not provide a text-to-speech option for users. #### Branding and design -- There's a recognizable brand for the project , a logo and blue-white color scheme used througout the website. -- The website design is good and suitable for reading. However, consider reducing space between the hero section and the Navbar. + +- There's a recognizable brand for the project , a logo and blue-white color + scheme used througout the website. +- The website design is good and suitable for reading. However, consider + reducing space between the hero section and the Navbar. #### Case studies/social proof -- There are case studies documented on the website under the *Adoptions* page. -- There's a logo wall of users or participating organizations documented in the *Adoptions* page. -- No avaliable community talks on the website. They have however provided links to the community channel. -- The available [TUF blog](https://theupdateframework.github.io/python-tuf) page is not available on the website. It's hosted on GitHub + +- There are case studies documented on the website under the _Adoptions_ page. +- There's a logo wall of users or participating organizations documented in the + _Adoptions_ page. +- No avaliable community talks on the website. They have however provided links + to the community channel. +- The available [TUF blog](https://theupdateframework.github.io/python-tuf) page + is not available on the website. It's hosted on GitHub #### SEO, Analytics and site-local search + - It's not clear what analytics are used on the site - Intra-site search is not available from the website - There's no mention of custodians of analytics and search. #### Maintenance planning -- The Website runs on Hugo and supported by -the community. -- It's not clear who are the maintainers of the website. +- The Website runs on Hugo and supported by the community. +- It's not clear who are the maintainers of the website. #### Other + - The website is accessible via HTTPS ### Recommendations #### Single-source requirement -- Rename the The website repo *theupdateframework.io* to a name that reflect it's content e.g *TUFwebsite.io*. It makes it easier to find. + +- Rename the The website repo _theupdateframework.io_ to a name that reflect + it's content e.g _TUFwebsite.io_. It makes it easier to find. #### Branding and design -- Reduce empty space between hero section and Navbar to bring information to eyelevel. At the moment the information is too far down, you have to scroll to find it. -#### SEO, Analytics and site-local search -- Provide intra-site search options such as a search button to make it easier for users to search and find information. +- Reduce empty space between hero section and Navbar to bring information to + eyelevel. At the moment the information is too far down, you have to scroll to + find it. -#### Case studies/social proof -- Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the website. - -#### Maintenance planning -- Identify website maintainers on the site and their roles so users know who to contact in case issues arise. -- Provide information about the website build and how to generate on the docs repo. +#### SEO, Analytics and site-local search +- Provide intra-site search options such as a search button to make it easier + for users to search and find information. +#### Case studies/social proof +- Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the + website. +#### Maintenance planning +- Identify website maintainers on the site and their roles so users know who to + contact in case issues arise. +- Provide information about the website build and how to generate on the docs + repo. +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 9569e78..1282cd1 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -3,11 +3,10 @@ title: Implementing TUF Doc Improvements tags: TUF --- - ## Introduction -This document provides actionable suggestions for improving the **theUpdateframework (TUF)** -technical documentation. +This document provides actionable suggestions for improving the +**theUpdateframework (TUF)** technical documentation. For an analysis and general discussion of recommendations on TUF technical documentation, see [analysis](./analysis.md). @@ -26,51 +25,60 @@ understood as "recommended" or "should" at the strongest, and "optional" or such, and pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: + - **Reorganize documentation** - Align sub-sections with related sections - Consolidate some pages into others to avoid repetition - - Add user roles to the 'Getting started' documentation - - Add a section for instructional material to website and repo documentation to make it easier to find. It can be a sub-section under 'Getting started' - + - Add user roles to the 'Getting started' documentation + - Add a section for instructional material to website and repo documentation + to make it easier to find. It can be a sub-section under 'Getting started' - **Introduce instructional documentation** - - Identify TUF user roles (personas) + + - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - - Document TUF installation procedures in a separate page(At the moment it's in the spec doc) + - Document TUF installation procedures in a separate page(At the moment it's + in the spec doc) - Develop quick start and contribution guides for new users - **Content maintanability and creation process** - - Rename the docs repo to a recognizable name e.g *TUF-ReadTheDocs* or similar + - Rename the docs repo to a recognizable name e.g _TUF-ReadTheDocs_ or similar - Add search functionality to website to make it easier to find content - - Identify maintainers for the docs repo - - Add labels to the docs repo - - Add a README to the docs repo with information about the project including links to important project repos + - Identify maintainers for the docs repo + - Add labels to the docs repo + - Add a README to the docs repo with information about the project including + links to important project repos - Develop a contributors' guideline for new users - Create procedure for developing the docs site locally - - Include communication channels on the Docs repo README - - Provide information about project meetings e.g a meeting link and calendar on both the website and repo - - Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the website. + - Include communication channels on the Docs repo README + - Provide information about project meetings e.g a meeting link and calendar + on both the website and repo + - Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the + website. ## Implementation ## Reorganize documentation ### Align sub-sections with related sections -Some sections listed on the menu bar have unrelated sub-sections. This structure makes information hard to find and can be confusing to new users. - I propose the following Navbar outline which includes the user roles. -- **About**: + +Some sections listed on the menu bar have unrelated sub-sections. This structure +makes information hard to find and can be confusing to new users. I propose the +following Navbar outline which includes the user roles. + +- **About**: - Overview - History - Project - Publications - Timeline -- **Getting started**: - - TUF security +- **Getting started**: + - TUF security - TUF specification (Roles and metadata,tutorials) - TUF proposals (linked to tutorials,videos) - TUF implementation/Developers (linked to tutorials,videos) - TUF docs (Link docs repo) - FAQ -- **Community**: +- **Community**: - Adoptions - Reporting issues - Security audits @@ -81,56 +89,99 @@ Some sections listed on the menu bar have unrelated sub-sections. This structure - Blog - News - Videos -- **Contact**: +- **Contact**: - CNCF slack, meeting links or calendar - -### Consolidate some pages -The specification index has been referenced several times on the website despite having its own sub-section. -I suggest that it remains in the project sub-section section under specification. But it be removed from the *Getting started* section. +### Consolidate some pages + +The specification index has been referenced several times on the website despite +having its own sub-section. + +I suggest that it remains in the project sub-section section under +specification. But it be removed from the _Getting started_ section. ### Add user roles to Getting started section -Structure the *Getting started* section according to user roles. See the suggested *Getting started* above. The percieved user roles for this project are: - - **TUF specification**: Uses TUF metadata to download and verify targets - - **TUF proposals contributor** : Proposes major changes to the specification, including new features made as TUF Augmentation Proposals (TAPs) - - **TUF implementation/Developers** : Develops software with the TUF Python reference implementation - - **TUF docs**: Contributes to documentation -Each role should have accompanying documentation and instructional material/tutorial to help users set up and start using TUF. +Structure the _Getting started_ section according to user roles. See the +suggested _Getting started_ above. The percieved user roles for this project +are: + +- **TUF specification**: Uses TUF metadata to download and verify targets +- **TUF proposals contributor** : Proposes major changes to the specification, + including new features made as TUF Augmentation Proposals (TAPs) +- **TUF implementation/Developers** : Develops software with the TUF Python + reference implementation +- **TUF docs**: Contributes to documentation + +Each role should have accompanying documentation and instructional +material/tutorial to help users set up and start using TUF. ## Introduce Instructional Material -- Clearly identify user roles in the documentation and what can be achieved by each -- Create instructional material in the *Getting started* section for each user role i.e How-to guides and tutorials -- Document installation guides for each user role in a separate page. At the moment all the information for [TUF Specification](https://theupdateframework.github.io/specification/latest) file. +- Clearly identify user roles in the documentation and what can be achieved by + each +- Create instructional material in the _Getting started_ section for each user + role i.e How-to guides and tutorials +- Document installation guides for each user role in a separate page. At the + moment all the information for + [TUF Specification](https://theupdateframework.github.io/specification/latest) + file. - Include links to the github repos associated with the role. ## Content maintainability and creation process ### Rename the docs Github repo - Rename the docs repo to a recognizable name e.g *TUF-ReadTheDocs* or similar to make it easier to find. At the moment, the repo is named *theupdateframework.io* which is too broad as it only contains docs and not all information about TUF projects + +Rename the docs repo to a recognizable name e.g _TUF-ReadTheDocs_ or similar to +make it easier to find. At the moment, the repo is named _theupdateframework.io_ +which is too broad as it only contains docs and not all information about TUF +projects ### Add README to docs repo -Add a README to the docs repo with information about the project. I suggest the following information: Overview of the project, components, project repos, communication channels and links a contributors' guide. + +Add a README to the docs repo with information about the project. I suggest the +following information: Overview of the project, components, project repos, +communication channels and links a contributors' guide. ### Add search functionality to website -Consider adding a search functionality to website to make it easier for users to do intra-site searching. Hugo does not have such functionality so I advice using a plugin. + +Consider adding a search functionality to website to make it easier for users to +do intra-site searching. Hugo does not have such functionality so I advice using +a plugin. + ### Identify maintainers for docs repo -Identify maintainers for the docs repo both on the website and repo to make it easier for contributors to contact them. + +Identify maintainers for the docs repo both on the website and repo to make it +easier for contributors to contact them. + ### Add labels to the docs repo -Include labels to issues in the docs repo. These includes labels such as *#docs #Goodfirstissue* to make it easier for contributors to get started. + +Include labels to issues in the docs repo. These includes labels such as _#docs +\#Goodfirstissue_ to make it easier for contributors to get started. ### Develop a contributors' guideline for new users - Develop contributor guides to assist new contributors to get started. + +Develop contributor guides to assist new contributors to get started. + ### Create procedures for developing the docs site locally - Develop procedures for developing the docs site locally i.e cloning, building and serving the documentation. You can also provide information about the tools used to build and maintain the site. When such information is available it helps contributors know how to improve the website. You might get some good suggestions. + +Develop procedures for developing the docs site locally i.e cloning, building +and serving the documentation. You can also provide information about the tools +used to build and maintain the site. When such information is available it helps +contributors know how to improve the website. You might get some good +suggestions. ### Provide project meeting links and calendar -Provide information about project meetings and a calendar on both the website and repo. Makes it easier for contributors to sinc with their calendars and get notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project have implemented this. -### Include the TUF log to website - Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the website. It has more visibility there than where it's located currently on the **Python/TUF repo** - - +Provide information about project meetings and a calendar on both the website +and repo. Makes it easier for contributors to sinc with their calendars and get +notifications about meetings. I like how the +[**Meshery**](https://github.com/layer5io/layer5) project have implemented this. + +### Include the TUF log to website +Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the +website. It has more visibility there than where it's located currently on the +**Python/TUF repo** +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 From ce6ac0234e589266a292fa3ab3a07c3f01cc92d5 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 1 Jul 2024 09:11:08 +0000 Subject: [PATCH 16/96] Correct phrases in docs according to rfc standards Signed-off-by: Dindihub Dindi --- .gitpod.yml | 8 ++++++++ analyses/0012-TUF/analysis.md | 30 ++++++++++++++--------------- analyses/0012-TUF/implementation.md | 6 +++--- 3 files changed, 26 insertions(+), 18 deletions(-) create mode 100644 .gitpod.yml diff --git a/.gitpod.yml b/.gitpod.yml new file mode 100644 index 0000000..0814e55 --- /dev/null +++ b/.gitpod.yml @@ -0,0 +1,8 @@ +# This configuration file was automatically generated by Gitpod. +# Please adjust to your needs (see https://www.gitpod.io/docs/introduction/learn-gitpod/gitpod-yaml) +# and commit this file to your remote git repository to share the goodness with others. + +# Learn more from ready-to-use templates: https://www.gitpod.io/docs/introduction/getting-started/quickstart + +tasks: + - init: npm install diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 8f3e524..2030843 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -6,7 +6,7 @@ modified: YYYY-MM-DD author: Sandra Dindi (@Dindihub) --- - + ## Introduction @@ -144,9 +144,9 @@ Scale: ### Summary of issues -- Information is repeated throughout the site. For example, the TUF - Specification file has been referenced in more than one page. Some pages can - be consolidated into others. +- Information is repeated is several pages of the website. For example, the TUF + Specification file is referenced in more than one page. Some pages can be + consolidated into others. - The website content needs restructuring to align sections with sub-sections related to their use case. For example, information in the sections should @@ -165,12 +165,12 @@ Scale: - Repetition of content on different pages makes content confusing -- Content needs to be re-organised to make it easier to follow +- Re-organise content to make it easier to follow - Docs do not have tutorials for specific feature implementation. But, there are videos explaining various use cases. -- There are not specific task-based guides for features. The available guide for +- There aren't specific task-based guides for features. The available guide for implementing the specification is part of a larger document labelled [Specification(latest)](https://theupdateframework.github.io/specification/latest) @@ -246,23 +246,23 @@ Scale: #### Information architecture -- Information should be re-organized on the website to better the workflow. For - example, each section should contain only related information. Consider the +- Information may be re-organized on the website to better the workflow. For + example, each section can contain only related information. Consider the following: - - The **About section** should only have introductory information about the + - The **About section** may contain only introductory information about the project in the following sequence. _Overview, History, Project and Publications, and Timeline_. The _Code of conduct_ should be moved to the Community section. - - The **Getting Started** section should contain information on how to use the + - The **Getting Started** section may contain information on how to use the software or contribute to the project. Consider the following sequence for this section:_Security,Roles and metadata,Implementations,Videos & Tutorials, and FAQs_. The _specification(latest) and Specification index_ pages should be removed because they are linked in the _Project page_ - Include _Code of conduct_ in the **Community section** - - The _Contribute_ page should include information of various areas of + - The _Contribute_ page can include information of various areas of contribution e.g The spec, repos etc and not to a specific repo. This way users can easily find areas of interest. @@ -295,9 +295,9 @@ Scale: - Include a search button on the website to make it easier for users to search and find content. -- The Docs repo should be the entry point of all repos. Meaning, the Docs README - should contain all the TUF project information including links to the other - repos and contributor guidelines. +- The Docs repo may be the entry point of all repos. Meaning, the Docs README + can contain all the TUF project information including links to the other repos + and contributor guidelines. #### Content creation processes @@ -398,7 +398,7 @@ Scale: #### Communication methods documented -- The documentation repo link should be included on the site as an entry point +- The documentation repo link may be included on the site as an entry point for the project. The repo can then include information about other repos. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings e.g a meeting link and calendar. diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 1282cd1..60dafc5 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -94,7 +94,7 @@ following Navbar outline which includes the user roles. ### Consolidate some pages -The specification index has been referenced several times on the website despite +The specification index is referenced several times on the website despite having its own sub-section. I suggest that it remains in the project sub-section section under @@ -113,7 +113,7 @@ are: reference implementation - **TUF docs**: Contributes to documentation -Each role should have accompanying documentation and instructional +Each role may have accompanying documentation and instructional material/tutorial to help users set up and start using TUF. ## Introduce Instructional Material @@ -176,7 +176,7 @@ suggestions. Provide information about project meetings and a calendar on both the website and repo. Makes it easier for contributors to sinc with their calendars and get notifications about meetings. I like how the -[**Meshery**](https://github.com/layer5io/layer5) project have implemented this. +[**Meshery**](https://github.com/layer5io/layer5) project has implemented this. ### Include the TUF log to website From aed9a2a4f79bf64db0a7ae9bdca8c3eeab11aafc Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 1 Jul 2024 15:21:51 +0000 Subject: [PATCH 17/96] Fix format in md files Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 2030843..a5ae594 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -6,7 +6,7 @@ modified: YYYY-MM-DD author: Sandra Dindi (@Dindihub) --- - + ## Introduction @@ -398,8 +398,8 @@ Scale: #### Communication methods documented -- The documentation repo link may be included on the site as an entry point - for the project. The repo can then include information about other repos. +- The documentation repo link may be included on the site as an entry point for + the project. The repo can then include information about other repos. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings e.g a meeting link and calendar. From a3188a22d57bd42d6972e1c8c1be4a8fd54bfd50 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 3 Jul 2024 08:49:44 +0300 Subject: [PATCH 18/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Patrice Chalin Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index a5ae594..142ce26 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -26,7 +26,7 @@ efforts. This document analyzes the current state of **The Update Framework (TUF)** documentation. It provides project leaders with an informed understanding of potential problems in current project documentation. A second -[implementation](./implementation.md) document, , outlines an actionable plan +[implementation](./implementation.md) document, outlines an actionable plan for improvement. A third document, the [issues](./issues.md) outlines issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. From 37e1fb482e37121155ac54883c3d5fc828ff9ee7 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 3 Jul 2024 08:50:09 +0300 Subject: [PATCH 19/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Patrice Chalin Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 142ce26..d9d6d52 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -49,9 +49,8 @@ is stored on the TUF GitHub repo. #### In scope -- Website: -- Documentation: -- Website configuration(Hugo): +- Website and docs: +- Website repo: #### Out of scope From da1e64dd71b1f0da552bcce091d004c3a3377553 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 3 Jul 2024 08:56:13 +0300 Subject: [PATCH 20/96] Update analyses/0012-TUF/implementation.md Co-authored-by: Patrice Chalin Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/implementation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 60dafc5..82b63fb 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -178,7 +178,7 @@ and repo. Makes it easier for contributors to sinc with their calendars and get notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. -### Include the TUF log to website +### Include the TUF blog to website Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the website. It has more visibility there than where it's located currently on the From 864388872d80077fd0aa8280e4ee0b8e6543a23b Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 5 Jul 2024 13:41:44 +0000 Subject: [PATCH 21/96] Add internal links to sections on analysis file and change IA in implementation file Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 71 ++++++++++++----------------- analyses/0012-TUF/implementation.md | 48 +++++++++---------- 2 files changed, 53 insertions(+), 66 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index d9d6d52..b8a07c3 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -26,10 +26,10 @@ efforts. This document analyzes the current state of **The Update Framework (TUF)** documentation. It provides project leaders with an informed understanding of potential problems in current project documentation. A second -[implementation](./implementation.md) document, outlines an actionable plan -for improvement. A third document, the [issues](./issues.md) outlines issues to -be added to the project documentation repository. These issues can be taken up -by contributors to improve the documentation. +[implementation](./implementation.md) document, outlines an actionable plan for +improvement. A third document, the [issues](./issues.md) outlines issues to be +added to the project documentation repository. These issues can be taken up by +contributors to improve the documentation. This document: @@ -50,20 +50,19 @@ is stored on the TUF GitHub repo. #### In scope - Website and docs: -- Website repo: - - -#### Out of scope - +- Website repo: - The TUF community repository: - TUF specification repository: +- TUF artwork repository: - Python reference implementation repository: + +#### Out of scope + - TUF Augmentation proposals repository: -- TUF artwork repository: ### How this document is organized @@ -103,9 +102,11 @@ Readers interested in the current state of the documentation and the reasoning behind the recommendations should read the section of this document pertaining to their area of concern: -- [Project documentation]() -- [Contributor documentation]() -- [Website and documentation infrastructure]() +- [Project documentation](#project-documentation) + +- [Contributor documentation](#contributor-documentation) + +- [Website and infastructure](#website-and-infrastructure) #### Recommendations, requirements, and best practices @@ -119,11 +120,11 @@ as "recommended" or "should" at the strongest, and "optional" or "may" in many cases. Any "must" or "required" actions are clearly denoted as such, and pertain to legal requirements such as copyright and licensing issues. -## Project Documentation +## Project documentation | Criteria | Rating (1-5) | | -------------------------- | ------------ | -| Information architecture | 3 | +| Information architecture | 2 | | New user content | 1 | | Content maintainability | 3 | | Content creation processes | 1 | @@ -166,7 +167,7 @@ Scale: - Re-organise content to make it easier to follow -- Docs do not have tutorials for specific feature implementation. But, there are +- There are no tutorials for specific feature implementation. But, there are videos explaining various use cases. - There aren't specific task-based guides for features. The available guide for @@ -241,29 +242,15 @@ Scale: - There is no use of abliest language like simple,easy in the documentation. -### Recommendations +### Project recommendations #### Information architecture -- Information may be re-organized on the website to better the workflow. For - example, each section can contain only related information. Consider the - following: - - - The **About section** may contain only introductory information about the - project in the following sequence. _Overview, History, Project and - Publications, and Timeline_. The _Code of conduct_ should be moved to the - Community section. - - - The **Getting Started** section may contain information on how to use the - software or contribute to the project. Consider the following sequence for - this section:_Security,Roles and metadata,Implementations,Videos & - Tutorials, and FAQs_. The _specification(latest) and Specification index_ - pages should be removed because they are linked in the _Project page_ - - - Include _Code of conduct_ in the **Community section** - - The _Contribute_ page can include information of various areas of - contribution e.g The spec, repos etc and not to a specific repo. This way - users can easily find areas of interest. +- Information can be re-organized on the website to better the workflow. That is + each section can contain only related information. For example, introduce a + documentation section that to consolidate other pages on the site. Much of the + information in the _About_ and _Getting started_ sections can go under a + _Docs_ section - Provide step-by-step tutorials for each use case on a separate page and label it as such. At the moment all the tutorials are included in a larger document @@ -294,14 +281,14 @@ Scale: - Include a search button on the website to make it easier for users to search and find content. -- The Docs repo may be the entry point of all repos. Meaning, the Docs README +- The website repo can be the entry point of all repos. Meaning, the Docs README can contain all the TUF project information including links to the other repos and contributor guidelines. #### Content creation processes -- Provide information about the Docs website such as the tools used and how to - set up ad run it locally. +- Provide information about the website such as the tools used and how to set up + ad run it locally on the website repo. - Provide information about the contribution process including having contribution guides on the website and the documentation repo. You can also @@ -320,7 +307,7 @@ Scale: with recommended suggestions in the [Inclusive language documentation](https://inclusivenaming.org/word-lists/tier-1/abort) -## Contributor Documentation +## Contributor documentation | Criteria | [Rating (1-5)] | | ----------------------------------------- | -------------- | @@ -393,7 +380,7 @@ Scale: informtaion about it's history including leaders,maintainers and contributors. However, this information is not visisble in the docs repo README. -### Recommendations +### Contributor recommendations #### Communication methods documented @@ -513,7 +500,7 @@ The website docs analysis is in progess. - The website is accessible via HTTPS -### Recommendations +### Website recommendations #### Single-source requirement diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 82b63fb..77623c4 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -63,42 +63,42 @@ The top-level documentation recommendations for this project are: Some sections listed on the menu bar have unrelated sub-sections. This structure makes information hard to find and can be confusing to new users. I propose the -following Navbar outline which includes the user roles. - -- **About**: - - Overview - - History - - Project - - Publications - - Timeline -- **Getting started**: - - TUF security - - TUF specification (Roles and metadata,tutorials) - - TUF proposals (linked to tutorials,videos) - - TUF implementation/Developers (linked to tutorials,videos) - - TUF docs (Link docs repo) - - FAQ -- **Community**: - - Adoptions - - Reporting issues - - Security audits - - Contribute : TAP, Docs - - Chat (CNCF slack) +following: + +- **About**: Overview of TUF project +- **Documentation**: +- Introduction to TUF +- TUF project components +- Getting started: TUF Specification, Standardization, reference implementation, + and documentation. You can include installation guides for each component in + this section +- Tutorials +- Implementations +- Best practises +- Contribution guidelines + +- **Community**: You can have two sections. + + - Learn and connect: Includes all community communication channels including + social media, mailing lists,calendar,Slack etc. + - Develop and Contribute : Information about how to contribute to TUF + components and documentation. - Code of conduct + - **Resources**: - Blog - News - Videos - **Contact**: - - CNCF slack, meeting links or calendar + - Maintainer info and TUF contact information ### Consolidate some pages The specification index is referenced several times on the website despite having its own sub-section. -I suggest that it remains in the project sub-section section under -specification. But it be removed from the _Getting started_ section. +You can have a docs section with information tailored to the user roles of the +three project components i.e ### Add user roles to Getting started section From e59901ba5e039e92bf811efa839bb12af4bd62f1 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 5 Jul 2024 14:11:32 +0000 Subject: [PATCH 22/96] Remove mention of Docs repo and correct typos Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 4 +-- analyses/0012-TUF/implementation.md | 45 ++++++++++++++--------------- 2 files changed, 23 insertions(+), 26 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index b8a07c3..c155fc0 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -246,9 +246,9 @@ Scale: #### Information architecture -- Information can be re-organized on the website to better the workflow. That is +- Information can be re-organized on the website to better the workflow. That is, each section can contain only related information. For example, introduce a - documentation section that to consolidate other pages on the site. Much of the + documentation section to consolidate other pages on the site. Much of the information in the _About_ and _Getting started_ sections can go under a _Docs_ section diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 77623c4..21c59b6 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -27,13 +27,12 @@ such, and pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: - **Reorganize documentation** - - Align sub-sections with related sections - - Consolidate some pages into others to avoid repetition - - Add user roles to the 'Getting started' documentation - - Add a section for instructional material to website and repo documentation - to make it easier to find. It can be a sub-section under 'Getting started' -- **Introduce instructional documentation** + - Introduce a docs section and place some pages under it to avoid repetition + - Structure 'Getting started' according to user roles + - Add instructional material to website and repo documentation + to make it easier to find. +- **Introduce instructional documentation** - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - Document TUF installation procedures in a separate page(At the moment it's @@ -41,15 +40,15 @@ The top-level documentation recommendations for this project are: - Develop quick start and contribution guides for new users - **Content maintanability and creation process** - - Rename the docs repo to a recognizable name e.g _TUF-ReadTheDocs_ or similar + - Rename the website repo to a recognizable name e.g _TUF-ReadTheDocs_ or similar - Add search functionality to website to make it easier to find content - - Identify maintainers for the docs repo - - Add labels to the docs repo - - Add a README to the docs repo with information about the project including + - Identify maintainers for the website repo + - Add labels to the website repo + - Add a README to the website repo with information about the project including links to important project repos - Develop a contributors' guideline for new users - - Create procedure for developing the docs site locally - - Include communication channels on the Docs repo README + - Create procedure for developing the website locally + - Include communication channels on the website repo README - Provide information about project meetings e.g a meeting link and calendar on both the website and repo - Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the @@ -59,11 +58,10 @@ The top-level documentation recommendations for this project are: ## Reorganize documentation -### Align sub-sections with related sections +### Align information in related sections Some sections listed on the menu bar have unrelated sub-sections. This structure -makes information hard to find and can be confusing to new users. I propose the -following: +makes information hard to find and can be confusing to new users. Much of the information on the website can go under a *Docs* section. Consider the following structure: - **About**: Overview of TUF project - **Documentation**: @@ -98,12 +96,11 @@ The specification index is referenced several times on the website despite having its own sub-section. You can have a docs section with information tailored to the user roles of the -three project components i.e +three project components. ### Add user roles to Getting started section -Structure the _Getting started_ section according to user roles. See the -suggested _Getting started_ above. The percieved user roles for this project +Structure the _Getting started_ section according to user roles under a *Docs* section. The percieved user roles for this project are: - **TUF specification**: Uses TUF metadata to download and verify targets @@ -130,16 +127,16 @@ material/tutorial to help users set up and start using TUF. ## Content maintainability and creation process -### Rename the docs Github repo +### Rename the website Github repo -Rename the docs repo to a recognizable name e.g _TUF-ReadTheDocs_ or similar to +Rename the website repo to a recognizable name e.g _TUF-website_ or similar to make it easier to find. At the moment, the repo is named _theupdateframework.io_ which is too broad as it only contains docs and not all information about TUF projects ### Add README to docs repo -Add a README to the docs repo with information about the project. I suggest the +Add a README to the website repo with information about the project. I suggest the following information: Overview of the project, components, project repos, communication channels and links a contributors' guide. @@ -149,14 +146,14 @@ Consider adding a search functionality to website to make it easier for users to do intra-site searching. Hugo does not have such functionality so I advice using a plugin. -### Identify maintainers for docs repo +### Identify maintainers for website repo -Identify maintainers for the docs repo both on the website and repo to make it +Identify maintainers for the website repo both on the website and repo to make it easier for contributors to contact them. ### Add labels to the docs repo -Include labels to issues in the docs repo. These includes labels such as _#docs +Include labels to issues in the website repo. These includes labels such as _#docs \#Goodfirstissue_ to make it easier for contributors to get started. ### Develop a contributors' guideline for new users From 314637928a3cecaf5b45e8186d5747cf0d9be830 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 5 Jul 2024 14:16:52 +0000 Subject: [PATCH 23/96] Remove typos in implementation file Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 21c59b6..b6ec759 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -27,7 +27,7 @@ such, and pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: - **Reorganize documentation** - - Introduce a docs section and place some pages under it to avoid repetition + - Introduce a docs section and place some sections like 'Getting started' under it to avoid repetition - Structure 'Getting started' according to user roles - Add instructional material to website and repo documentation to make it easier to find. From b0e9ac4f83b7e8928f607c5e649a4f253f6fd30c Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 5 Jul 2024 15:52:18 +0000 Subject: [PATCH 24/96] Fix formatting issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 6 ++--- analyses/0012-TUF/implementation.md | 36 +++++++++++++++++------------ 2 files changed, 24 insertions(+), 18 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index c155fc0..2a6c10c 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -246,9 +246,9 @@ Scale: #### Information architecture -- Information can be re-organized on the website to better the workflow. That is, - each section can contain only related information. For example, introduce a - documentation section to consolidate other pages on the site. Much of the +- Information can be re-organized on the website to better the workflow. That + is, each section can contain only related information. For example, introduce + a documentation section to consolidate other pages on the site. Much of the information in the _About_ and _Getting started_ sections can go under a _Docs_ section diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index b6ec759..6307053 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -27,12 +27,15 @@ such, and pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: - **Reorganize documentation** - - Introduce a docs section and place some sections like 'Getting started' under it to avoid repetition + + - Introduce a docs section and place some sections like 'Getting started' + under it to avoid repetition - Structure 'Getting started' according to user roles - - Add instructional material to website and repo documentation - to make it easier to find. + - Add instructional material to website and repo documentation to make it + easier to find. - **Introduce instructional documentation** + - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - Document TUF installation procedures in a separate page(At the moment it's @@ -40,12 +43,13 @@ The top-level documentation recommendations for this project are: - Develop quick start and contribution guides for new users - **Content maintanability and creation process** - - Rename the website repo to a recognizable name e.g _TUF-ReadTheDocs_ or similar + - Rename the website repo to a recognizable name e.g _TUF-ReadTheDocs_ or + similar - Add search functionality to website to make it easier to find content - Identify maintainers for the website repo - Add labels to the website repo - - Add a README to the website repo with information about the project including - links to important project repos + - Add a README to the website repo with information about the project + including links to important project repos - Develop a contributors' guideline for new users - Create procedure for developing the website locally - Include communication channels on the website repo README @@ -61,7 +65,9 @@ The top-level documentation recommendations for this project are: ### Align information in related sections Some sections listed on the menu bar have unrelated sub-sections. This structure -makes information hard to find and can be confusing to new users. Much of the information on the website can go under a *Docs* section. Consider the following structure: +makes information hard to find and can be confusing to new users. Much of the +information on the website can go under a _Docs_ section. Consider the following +structure: - **About**: Overview of TUF project - **Documentation**: @@ -100,8 +106,8 @@ three project components. ### Add user roles to Getting started section -Structure the _Getting started_ section according to user roles under a *Docs* section. The percieved user roles for this project -are: +Structure the _Getting started_ section according to user roles under a _Docs_ +section. The percieved user roles for this project are: - **TUF specification**: Uses TUF metadata to download and verify targets - **TUF proposals contributor** : Proposes major changes to the specification, @@ -136,8 +142,8 @@ projects ### Add README to docs repo -Add a README to the website repo with information about the project. I suggest the -following information: Overview of the project, components, project repos, +Add a README to the website repo with information about the project. I suggest +the following information: Overview of the project, components, project repos, communication channels and links a contributors' guide. ### Add search functionality to website @@ -148,13 +154,13 @@ a plugin. ### Identify maintainers for website repo -Identify maintainers for the website repo both on the website and repo to make it -easier for contributors to contact them. +Identify maintainers for the website repo both on the website and repo to make +it easier for contributors to contact them. ### Add labels to the docs repo -Include labels to issues in the website repo. These includes labels such as _#docs -\#Goodfirstissue_ to make it easier for contributors to get started. +Include labels to issues in the website repo. These includes labels such as +_#docs \#Goodfirstissue_ to make it easier for contributors to get started. ### Develop a contributors' guideline for new users From ea349fcaa88df03f19c22de4cc0eed6763343106 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Sun, 7 Jul 2024 12:02:55 +0300 Subject: [PATCH 25/96] Correct typos on implementation.md Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/implementation.md | 79 ++++++++++++++--------------- 1 file changed, 38 insertions(+), 41 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 6307053..ece49cd 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -14,44 +14,44 @@ documentation, see [analysis](./analysis.md). ### Recommendations, requirements, and best practices This analysis measures documentation against CNCF project maturity standards and -suggests possible improvements. In most cases there is more than one way to do +suggests possible improvements. In most cases, there is more than one way to do things. Few recommendations here are meant to be prescriptive. Rather, recommendations are based on documentation best practices as understood by the reviewers. The recommended implementations represent the reviewers' experience with how to apply those best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or -"may" in many cases. Any "must" or "required" actions are clearly denoted as -such, and pertain to legal requirements such as copyright and licensing issues. +"may" in many cases. Any "must" or "required" actions are denoted as +such and pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: - **Reorganize documentation** - - Introduce a docs section and place some sections like 'Getting started' + - Introduce a docs section and place some sections like **Getting started** under it to avoid repetition - Structure 'Getting started' according to user roles - - Add instructional material to website and repo documentation to make it + - Add instructional material to the website and repo documentation to make it easier to find. - **Introduce instructional documentation** - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - - Document TUF installation procedures in a separate page(At the moment it's + - Document TUF installation procedures on a separate page(At the moment, it's in the spec doc) - Develop quick start and contribution guides for new users -- **Content maintanability and creation process** +- **Content maintainability and creation process** - Rename the website repo to a recognizable name e.g _TUF-ReadTheDocs_ or similar - - Add search functionality to website to make it easier to find content + - Add search functionality to the website to make it easier to find content - Identify maintainers for the website repo - Add labels to the website repo - Add a README to the website repo with information about the project including links to important project repos - Develop a contributors' guideline for new users - - Create procedure for developing the website locally + - Create procedural material for developing the website locally - Include communication channels on the website repo README - Provide information about project meetings e.g a meeting link and calendar on both the website and repo @@ -68,24 +68,22 @@ Some sections listed on the menu bar have unrelated sub-sections. This structure makes information hard to find and can be confusing to new users. Much of the information on the website can go under a _Docs_ section. Consider the following structure: - - **About**: Overview of TUF project - **Documentation**: -- Introduction to TUF -- TUF project components -- Getting started: TUF Specification, Standardization, reference implementation, + - Introduction to TUF + - TUF project components + - Getting started: TUF Specification, Standardization, reference implementation, and documentation. You can include installation guides for each component in this section -- Tutorials -- Implementations -- Best practises -- Contribution guidelines + - Tutorials + - Implementations + - Best practices + - Contribution guidelines - **Community**: You can have two sections. - - Learn and connect: Includes all community communication channels including - social media, mailing lists,calendar,Slack etc. - - Develop and Contribute : Information about how to contribute to TUF + social media, mailing lists, calendars, Slack, etc. + - Develop and Contribute: Information about how to contribute to TUF components and documentation. - Code of conduct @@ -99,18 +97,18 @@ structure: ### Consolidate some pages The specification index is referenced several times on the website despite -having its own sub-section. +having a sub-section. -You can have a docs section with information tailored to the user roles of the +You can have a **docs section** with information tailored to the user roles of the three project components. -### Add user roles to Getting started section +### Add user roles to the Getting Started section -Structure the _Getting started_ section according to user roles under a _Docs_ -section. The percieved user roles for this project are: +Structure the _Getting Started_ section according to user roles under a _Docs_ +section. The perceived user roles for this project are: - **TUF specification**: Uses TUF metadata to download and verify targets -- **TUF proposals contributor** : Proposes major changes to the specification, +- **TUF proposals contributor**: Proposes major changes to the specification, including new features made as TUF Augmentation Proposals (TAPs) - **TUF implementation/Developers** : Develops software with the TUF Python reference implementation @@ -121,21 +119,21 @@ material/tutorial to help users set up and start using TUF. ## Introduce Instructional Material -- Clearly identify user roles in the documentation and what can be achieved by +- Identify user roles in the documentation and what can be achieved by each -- Create instructional material in the _Getting started_ section for each user - role i.e How-to guides and tutorials -- Document installation guides for each user role in a separate page. At the - moment all the information for +- Create instructional material in the _Getting Started_ section for each user + role i.e how-to guides and tutorials +- Document installation guides for each user role on a separate page. At the + moment, all the information for [TUF Specification](https://theupdateframework.github.io/specification/latest) file. -- Include links to the github repos associated with the role. +- Include links to the GitHub repos associated with the role. ## Content maintainability and creation process ### Rename the website Github repo -Rename the website repo to a recognizable name e.g _TUF-website_ or similar to +Rename the website repo to a recognizable name e.g. _TUF-website_ or similar to make it easier to find. At the moment, the repo is named _theupdateframework.io_ which is too broad as it only contains docs and not all information about TUF projects @@ -148,9 +146,9 @@ communication channels and links a contributors' guide. ### Add search functionality to website -Consider adding a search functionality to website to make it easier for users to -do intra-site searching. Hugo does not have such functionality so I advice using -a plugin. +Consider adding a search functionality to the website to make it easier for users to +do intra-site searching. Hugo does not have such functionality so I suggest using +a plugin or migrating to a theme that has search functionality. ### Identify maintainers for website repo @@ -159,7 +157,7 @@ it easier for contributors to contact them. ### Add labels to the docs repo -Include labels to issues in the website repo. These includes labels such as +Include labels to issues in the website repo. These include labels such as _#docs \#Goodfirstissue_ to make it easier for contributors to get started. ### Develop a contributors' guideline for new users @@ -168,8 +166,7 @@ Develop contributor guides to assist new contributors to get started. ### Create procedures for developing the docs site locally -Develop procedures for developing the docs site locally i.e cloning, building -and serving the documentation. You can also provide information about the tools +Develop procedures for developing the docs site locally i.e. cloning, building, and serving the documentation. You can also provide information about the tools used to build and maintain the site. When such information is available it helps contributors know how to improve the website. You might get some good suggestions. @@ -177,11 +174,11 @@ suggestions. ### Provide project meeting links and calendar Provide information about project meetings and a calendar on both the website -and repo. Makes it easier for contributors to sinc with their calendars and get +and repo. Makes it easier for contributors to sync with their calendars and get notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. -### Include the TUF blog to website +### Include the TUF blog on the website Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the website. It has more visibility there than where it's located currently on the From d639caad8a76c9cf3208969d19ee439f740f9d07 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sun, 7 Jul 2024 09:22:56 +0000 Subject: [PATCH 26/96] Fix formatting issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index ece49cd..c393c44 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -21,8 +21,8 @@ reviewers. The recommended implementations represent the reviewers' experience with how to apply those best practices. In other words, borrowing terminology from the lexicon of [RFCs][rfc-keywords], the changes described here should be understood as "recommended" or "should" at the strongest, and "optional" or -"may" in many cases. Any "must" or "required" actions are denoted as -such and pertain to legal requirements such as copyright and licensing issues. +"may" in many cases. Any "must" or "required" actions are denoted as such and +pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: @@ -68,19 +68,22 @@ Some sections listed on the menu bar have unrelated sub-sections. This structure makes information hard to find and can be confusing to new users. Much of the information on the website can go under a _Docs_ section. Consider the following structure: + - **About**: Overview of TUF project - **Documentation**: + - Introduction to TUF - TUF project components - - Getting started: TUF Specification, Standardization, reference implementation, - and documentation. You can include installation guides for each component in - this section + - Getting started: TUF Specification, Standardization, reference + implementation, and documentation. You can include installation guides for + each component in this section - Tutorials - Implementations - Best practices - Contribution guidelines - **Community**: You can have two sections. + - Learn and connect: Includes all community communication channels including social media, mailing lists, calendars, Slack, etc. - Develop and Contribute: Information about how to contribute to TUF @@ -99,8 +102,8 @@ structure: The specification index is referenced several times on the website despite having a sub-section. -You can have a **docs section** with information tailored to the user roles of the -three project components. +You can have a **docs section** with information tailored to the user roles of +the three project components. ### Add user roles to the Getting Started section @@ -119,8 +122,7 @@ material/tutorial to help users set up and start using TUF. ## Introduce Instructional Material -- Identify user roles in the documentation and what can be achieved by - each +- Identify user roles in the documentation and what can be achieved by each - Create instructional material in the _Getting Started_ section for each user role i.e how-to guides and tutorials - Document installation guides for each user role on a separate page. At the @@ -146,9 +148,9 @@ communication channels and links a contributors' guide. ### Add search functionality to website -Consider adding a search functionality to the website to make it easier for users to -do intra-site searching. Hugo does not have such functionality so I suggest using -a plugin or migrating to a theme that has search functionality. +Consider adding a search functionality to the website to make it easier for +users to do intra-site searching. Hugo does not have such functionality so I +suggest using a plugin or migrating to a theme that has search functionality. ### Identify maintainers for website repo @@ -166,7 +168,8 @@ Develop contributor guides to assist new contributors to get started. ### Create procedures for developing the docs site locally -Develop procedures for developing the docs site locally i.e. cloning, building, and serving the documentation. You can also provide information about the tools +Develop procedures for developing the docs site locally i.e. cloning, building, +and serving the documentation. You can also provide information about the tools used to build and maintain the site. When such information is available it helps contributors know how to improve the website. You might get some good suggestions. From a1f68c4e8b290624edd7dc3f3e7960c22a261f13 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sun, 7 Jul 2024 09:32:10 +0000 Subject: [PATCH 27/96] Fix formatting issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 2a6c10c..369b7c8 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -478,7 +478,7 @@ The website docs analysis is in progess. #### Case studies/social proof - There are case studies documented on the website under the _Adoptions_ page. -- There's a logo wall of users or participating organizations documented in the +- There's a logo, wall of users and participating organizations documented in the _Adoptions_ page. - No avaliable community talks on the website. They have however provided links to the community channel. @@ -493,7 +493,7 @@ The website docs analysis is in progess. #### Maintenance planning -- The Website runs on Hugo and supported by the community. +- The website runs on Hugo and supported by the community. - It's not clear who are the maintainers of the website. #### Other @@ -504,7 +504,7 @@ The website docs analysis is in progess. #### Single-source requirement -- Rename the The website repo _theupdateframework.io_ to a name that reflect +- Rename the website repo _theupdateframework.io_ to a name that reflect it's content e.g _TUFwebsite.io_. It makes it easier to find. #### Branding and design From 19d0395e44ada4b80d1be343ae5a86733c08dbb4 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sun, 7 Jul 2024 09:33:43 +0000 Subject: [PATCH 28/96] Fix formatting issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 369b7c8..14d0910 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -478,8 +478,8 @@ The website docs analysis is in progess. #### Case studies/social proof - There are case studies documented on the website under the _Adoptions_ page. -- There's a logo, wall of users and participating organizations documented in the - _Adoptions_ page. +- There's a logo, wall of users and participating organizations documented in + the _Adoptions_ page. - No avaliable community talks on the website. They have however provided links to the community channel. - The available [TUF blog](https://theupdateframework.github.io/python-tuf) page @@ -504,8 +504,8 @@ The website docs analysis is in progess. #### Single-source requirement -- Rename the website repo _theupdateframework.io_ to a name that reflect - it's content e.g _TUFwebsite.io_. It makes it easier to find. +- Rename the website repo _theupdateframework.io_ to a name that reflect it's + content e.g _TUFwebsite.io_. It makes it easier to find. #### Branding and design From 860f28a980ab352082b33abdd6a4c3730528c292 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:43:13 +0300 Subject: [PATCH 29/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 14d0910..9f006c7 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -176,7 +176,7 @@ Scale: - There is a FAQ and reporting issues sections for troubleshooting. -- There is a a well detailed API reference for multiple TUF APIs +- There is a well detailed API reference for multiple TUF APIs - README on [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) From f1dbeafebc739844dadae4b0d2b02706c9c23013 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:44:18 +0300 Subject: [PATCH 30/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 9f006c7..fec70f9 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -144,7 +144,7 @@ Scale: ### Summary of issues -- Information is repeated is several pages of the website. For example, the TUF +- Information is repeated on several pages of the website. For example, the TUF Specification file is referenced in more than one page. Some pages can be consolidated into others. From 911e7d0feaaf652b455aa6c344a86e0a585e5fc0 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:45:17 +0300 Subject: [PATCH 31/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index fec70f9..1793343 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -145,7 +145,7 @@ Scale: ### Summary of issues - Information is repeated on several pages of the website. For example, the TUF - Specification file is referenced in more than one page. Some pages can be + Specification file is referenced on more than one page. Some pages can be consolidated into others. - The website content needs restructuring to align sections with sub-sections From b113cd27573023202d17775d2a93ca2d8115788a Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:46:04 +0300 Subject: [PATCH 32/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 1793343..c29b585 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -473,7 +473,7 @@ The website docs analysis is in progess. - There's a recognizable brand for the project , a logo and blue-white color scheme used througout the website. - The website design is good and suitable for reading. However, consider - reducing space between the hero section and the Navbar. + reducing the space between the hero section and the Navbar. #### Case studies/social proof From 7f0ee4a203f0b454bebec88501a4d07d916e3906 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:46:50 +0300 Subject: [PATCH 33/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index c29b585..535b5b4 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -480,7 +480,7 @@ The website docs analysis is in progess. - There are case studies documented on the website under the _Adoptions_ page. - There's a logo, wall of users and participating organizations documented in the _Adoptions_ page. -- No avaliable community talks on the website. They have however provided links +- No available community talks on the website. They have however provided links to the community channel. - The available [TUF blog](https://theupdateframework.github.io/python-tuf) page is not available on the website. It's hosted on GitHub From 05d2927ceb30543438bf70cd81a769cc564e7cdd Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:47:17 +0300 Subject: [PATCH 34/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 535b5b4..61b6144 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -27,7 +27,7 @@ This document analyzes the current state of **The Update Framework (TUF)** documentation. It provides project leaders with an informed understanding of potential problems in current project documentation. A second [implementation](./implementation.md) document, outlines an actionable plan for -improvement. A third document, the [issues](./issues.md) outlines issues to be +improvement. A third [issues](./issues.md) document, outlines the issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. From 7b2f842c217780c32402610fda8ab28f43471477 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:47:38 +0300 Subject: [PATCH 35/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 61b6144..764615f 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -180,7 +180,7 @@ Scale: - README on [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) - repo is empty with little information about content of the repo. + repo is empty with little information about the content of the repo. #### New user content From cdca921bb6de74e6870e31a1a2b2d5a5ae2ed58a Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:48:01 +0300 Subject: [PATCH 36/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 764615f..33e95c4 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -505,7 +505,7 @@ The website docs analysis is in progess. #### Single-source requirement - Rename the website repo _theupdateframework.io_ to a name that reflect it's - content e.g _TUFwebsite.io_. It makes it easier to find. + content, e.g., _TUFwebsite.io_. It makes it easier to find. #### Branding and design From 4223878d08ed66260e6ae39e2da331c2d7f26c38 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:48:20 +0300 Subject: [PATCH 37/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 33e95c4..8d871a9 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -509,7 +509,7 @@ The website docs analysis is in progess. #### Branding and design -- Reduce empty space between hero section and Navbar to bring information to +- Reduce the empty space between the hero section and Navbar to bring information to eyelevel. At the moment the information is too far down, you have to scroll to find it. From f2d6ac387c41c67e8bde2bbb60f1a30fdcc44108 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:48:40 +0300 Subject: [PATCH 38/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 8d871a9..190e6d3 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -527,7 +527,7 @@ The website docs analysis is in progess. - Identify website maintainers on the site and their roles so users know who to contact in case issues arise. -- Provide information about the website build and how to generate on the docs +- Provide information about the website build and how to generate it on the docs repo. [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 From c602015ab9df4a8e88b5035f45c88332c9ff7c1e Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Mon, 8 Jul 2024 09:49:08 +0300 Subject: [PATCH 39/96] Update analyses/0012-TUF/implementation.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/implementation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index c393c44..f4b1411 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -38,7 +38,7 @@ The top-level documentation recommendations for this project are: - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - - Document TUF installation procedures on a separate page(At the moment, it's + - Document TUF installation procedures on a separate page (At the moment, it's in the spec doc) - Develop quick start and contribution guides for new users From 61bf85e29834947099ff9fddd8c9a27a32b86eed Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 17 Jul 2024 20:54:29 +0300 Subject: [PATCH 40/96] Update analyses/0012-TUF/analysis.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lukas Pühringer Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 190e6d3..66b6e5d 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -77,7 +77,7 @@ concern: branding, website structure, and maintainability. Each section begins with summary ratings based on a rubric with appropriate -[criteria] for the section, then proceeds to: +criteria for the section, then proceeds to: - **Comments**: Observations about the existing documentation, with a focus on how it does or does not help TUF project users achieve their goals. From a5da7921e7fc90360fa69d293f39fcdd3ddd126b Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 17 Jul 2024 20:54:44 +0300 Subject: [PATCH 41/96] Update analyses/0012-TUF/analysis.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lukas Pühringer Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 66b6e5d..a40bdf4 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -192,7 +192,7 @@ Scale: - The documentation repo does not have a contributor guide for new users to get started -- There isin't any documentation labeled 'Installation guide'. Instead, +- There isn't any documentation labeled 'Installation guide'. Instead, installation instructions are part of a larger document labelled [The Update Framework specification](https://theupdateframework.github.io/specification/latest) From 1de2123a91e8e5f8e8730d1f07b639a7fc9d5772 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 17 Jul 2024 21:05:08 +0300 Subject: [PATCH 42/96] Update analyses/0012-TUF/analysis.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lukas Pühringer Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index a40bdf4..456ab6e 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -377,7 +377,7 @@ Scale: #### Project governance documentation - The project governance is well documented on the website. There's sufficient - informtaion about it's history including leaders,maintainers and contributors. + informtaion about it's history including leaders, maintainers and contributors. However, this information is not visisble in the docs repo README. ### Contributor recommendations From 7fd717204cb7fa3639648a2e826c94a31c5f5e95 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 19:24:16 +0000 Subject: [PATCH 43/96] Input Lukas suggestions Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 30 ++++++++---------- analyses/0012-TUF/implementation.md | 47 +++++++++-------------------- 2 files changed, 28 insertions(+), 49 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 190e6d3..fd26647 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -16,10 +16,8 @@ This document analyzes the effectiveness and completeness of as part of its overall effort to incubate, grow, and graduate open source cloud native software projects. -According to CNCF best practices guidelines, effective documentation is a -prerequisite for program graduation. The documentation analysis is the first -step of a CNCF process aimed at assisting projects with their documentation -efforts. +TUF is a graduated CNCF project. The documentation analysis is the first step of +a CNCF process aimed at assisting projects with their documentation efforts. ### Purpose @@ -189,12 +187,14 @@ Scale: the _Specification (latest)_ and _index_ include information present in the project and overview sections. This section is confusing for new users. -- The documentation repo does not have a contributor guide for new users to get +- The website repo does not have guides for new users or contributors to get started -- There isin't any documentation labeled 'Installation guide'. Instead, - installation instructions are part of a larger document labelled - [The Update Framework specification](https://theupdateframework.github.io/specification/latest) +- There are no installation guides because TUF is a specification.There are + several TUF libraries (python, go, etc.), which can be used to implement a + TUF-powered repository and client. Also, there are TUF repository applications + (tuf-on-ci, RSTUF), which provide specific but reusable TUF repositories, plus + tooling to use them. - TUF docs do not provide information about application-specific/OS functionality in system updates. Instead the documentation states that TUF @@ -369,8 +369,8 @@ Scale: - There's a community section on the website with information on how to join the community. -- No specific documentation tailored for new users to get started the software - on the website or the docs repo. +- No specific documentation tailored to new users to get started to set up the + website. - The docs provide several channels for reporting issues, contacting the maintainers, and slack community. @@ -438,12 +438,8 @@ Scale: ### Summary of Issues -- The website repo is named _theupdateframework.io_ which makes it harder to - identify it. Name it according to it's content. - There's no guideline or tutorial to assist users to generate the website from the website repo. -- The available [TUF blog](https://theupdateframework.github.io/python-tuf) page - is not available on the website. It's hosted on GitHub. - Information about the website build, tools and how to generate it are not available on the website or the docs repo. - Intra-site search mechanism is not available from the website. The only @@ -509,9 +505,9 @@ The website docs analysis is in progess. #### Branding and design -- Reduce the empty space between the hero section and Navbar to bring information to - eyelevel. At the moment the information is too far down, you have to scroll to - find it. +- Reduce the empty space between the hero section and Navbar to bring + information to eyelevel. At the moment the information is too far down, you + have to scroll to find it. #### SEO, Analytics and site-local search diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index f4b1411..e86f570 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -80,7 +80,6 @@ structure: - Tutorials - Implementations - Best practices - - Contribution guidelines - **Community**: You can have two sections. @@ -91,11 +90,9 @@ structure: - Code of conduct - **Resources**: - - Blog - News - Videos -- **Contact**: - - Maintainer info and TUF contact information + - Publications and press ### Consolidate some pages @@ -110,37 +107,29 @@ the three project components. Structure the _Getting Started_ section according to user roles under a _Docs_ section. The perceived user roles for this project are: -- **TUF specification**: Uses TUF metadata to download and verify targets -- **TUF proposals contributor**: Proposes major changes to the specification, - including new features made as TUF Augmentation Proposals (TAPs) -- **TUF implementation/Developers** : Develops software with the TUF Python - reference implementation -- **TUF docs**: Contributes to documentation +- **Adopters**: Integrate TUF security properties into new and existing content + delivery systems. Adopters can be classified into two categories: -Each role may have accompanying documentation and instructional -material/tutorial to help users set up and start using TUF. + - **Client maintainers**: depend on repository maintainers, to provide a TUF + repo. And they can choose from multiple TUF client implementations + (python-tuf, go-tuf, etc.) . Typically, they will pick the language their + client is written in. + - **Repository maintainers** can either use an existing TUF repository + implementation (tuf-on-ci, RSTUF), or roll their own (typically using a tuf + repository library such as python-tuf, go-tuf, etc.) + +- **Contributors**: want to contribute either to the spec or documentation. ## Introduce Instructional Material - Identify user roles in the documentation and what can be achieved by each - Create instructional material in the _Getting Started_ section for each user role i.e how-to guides and tutorials -- Document installation guides for each user role on a separate page. At the - moment, all the information for - [TUF Specification](https://theupdateframework.github.io/specification/latest) - file. - Include links to the GitHub repos associated with the role. ## Content maintainability and creation process -### Rename the website Github repo - -Rename the website repo to a recognizable name e.g. _TUF-website_ or similar to -make it easier to find. At the moment, the repo is named _theupdateframework.io_ -which is too broad as it only contains docs and not all information about TUF -projects - -### Add README to docs repo +### Add README to website repo Add a README to the website repo with information about the project. I suggest the following information: Overview of the project, components, project repos, @@ -157,12 +146,12 @@ suggest using a plugin or migrating to a theme that has search functionality. Identify maintainers for the website repo both on the website and repo to make it easier for contributors to contact them. -### Add labels to the docs repo +### Add labels to the website repo Include labels to issues in the website repo. These include labels such as _#docs \#Goodfirstissue_ to make it easier for contributors to get started. -### Develop a contributors' guideline for new users +### Develop a guidelines for new users and contributors Develop contributor guides to assist new contributors to get started. @@ -181,10 +170,4 @@ and repo. Makes it easier for contributors to sync with their calendars and get notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. -### Include the TUF blog on the website - -Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the -website. It has more visibility there than where it's located currently on the -**Python/TUF repo** - [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 From 2b0182dd3cfa24b9920fd31fa193ca4d76f1a095 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 19:31:54 +0000 Subject: [PATCH 44/96] Fix formatting issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index c56fbb2..cd98d6f 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -377,8 +377,9 @@ Scale: #### Project governance documentation - The project governance is well documented on the website. There's sufficient - informtaion about it's history including leaders, maintainers and contributors. - However, this information is not visisble in the docs repo README. + informtaion about it's history including leaders, maintainers and + contributors. However, this information is not visisble in the docs repo + README. ### Contributor recommendations From f740bceee907da5ee4ba55a19078edce6fe31750 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 19:35:57 +0000 Subject: [PATCH 45/96] Edit text in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index e86f570..9c8c9f2 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -105,7 +105,8 @@ the three project components. ### Add user roles to the Getting Started section Structure the _Getting Started_ section according to user roles under a _Docs_ -section. The perceived user roles for this project are: +section. The perceived user roles for this project are Adopters and +Contributors: - **Adopters**: Integrate TUF security properties into new and existing content delivery systems. Adopters can be classified into two categories: From dfb06fb574e73ff2aacf53e414126b21e0e43fcf Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 19:40:07 +0000 Subject: [PATCH 46/96] Edit text in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 9c8c9f2..4a80db5 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -111,11 +111,11 @@ Contributors: - **Adopters**: Integrate TUF security properties into new and existing content delivery systems. Adopters can be classified into two categories: - - **Client maintainers**: depend on repository maintainers, to provide a TUF + - _Client maintainers_: depend on repository maintainers, to provide a TUF repo. And they can choose from multiple TUF client implementations - (python-tuf, go-tuf, etc.) . Typically, they will pick the language their + (python-tuf, go-tuf, etc.) Typically, they will pick the language their client is written in. - - **Repository maintainers** can either use an existing TUF repository + - _Repository maintainers_: Use either an existing TUF repository implementation (tuf-on-ci, RSTUF), or roll their own (typically using a tuf repository library such as python-tuf, go-tuf, etc.) From 85ffa92cad4ce04a07888cf8081afe2e289a03a3 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 20:02:18 +0000 Subject: [PATCH 47/96] Edit text in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 47 +++++++++-------------------- analyses/0012-TUF/implementation.md | 15 ++------- 2 files changed, 18 insertions(+), 44 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index cd98d6f..0d38b9c 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -168,9 +168,7 @@ Scale: - There are no tutorials for specific feature implementation. But, there are videos explaining various use cases. -- There aren't specific task-based guides for features. The available guide for - implementing the specification is part of a larger document labelled - [Specification(latest)](https://theupdateframework.github.io/specification/latest) +- There aren't specific task-based guides for features. - There is a FAQ and reporting issues sections for troubleshooting. @@ -252,14 +250,13 @@ Scale: information in the _About_ and _Getting started_ sections can go under a _Docs_ section -- Provide step-by-step tutorials for each use case on a separate page and label - it as such. At the moment all the tutorials are included in a larger document - the _Specification(latest)_ +- Provide step-by-step tutorials for users on a separate page and label it as + such. -- Create a **README** on the documentation repo with information detailing the - content of the repo. Also include a **contribution guide** and information of - how to set up the website and run it locally for new contributors. You can - include a getting started section on the README. +- Create a **README** on the website repo with information detailing the content + of the repo. Also include a **contribution guide** and information of how to + set up the website and run it locally for new contributors. You can include a + getting started section on the README. #### New user content @@ -270,12 +267,6 @@ Scale: - Include a **README** in the documentation repo with a contributor guide on how to get started with Docs. -- Create an _Installation guide_ on a separate page. This can contain - step-to-step instructions for diffent users including beginners. Installation - instructions in the - [The Update Framework specification](https://theupdateframework.github.io/specification/latest) - can be included here. - #### Content maintainability & site mechanics - Include a search button on the website to make it easier for users to search @@ -331,8 +322,8 @@ Scale: ### Summary of Issues - The documentation does not contain information tailored to contributors. -- Information about TUF communication channels is not visible in the docs repo. - But the information is available on the website. +- Information about TUF communication channels is not visible in the website + repo. But the information is available on the website. - The documentation does not contain information about other project repos and their links. Making it harder for contributors to find them. - The documentation repo issues do not appear to be maintained. There are old @@ -345,7 +336,7 @@ Scale: - Information about the TUF **slack channel** is available on the website on both the Community and Contact sections. However,this information should be - visible on the doc repo README for easy access. + visible on the website repo README for easy access. - The repo link on the website does not point to the documentation but rather the @@ -385,8 +376,10 @@ Scale: #### Communication methods documented -- The documentation repo link may be included on the site as an entry point for - the project. The repo can then include information about other repos. +- The website repo link may be included on the site as an entry point for the + project or the umbrella repo + [theupdateframework](https://github.com/theupdateframework) that lists all TUF + repositories. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings e.g a meeting link and calendar. @@ -456,7 +449,7 @@ Scale: #### Minimal website requirements -The website docs analysis is in progess. +The website docs analysis is in progress. #### Usability, accessibility and devices @@ -499,11 +492,6 @@ The website docs analysis is in progess. ### Website recommendations -#### Single-source requirement - -- Rename the website repo _theupdateframework.io_ to a name that reflect it's - content, e.g., _TUFwebsite.io_. It makes it easier to find. - #### Branding and design - Reduce the empty space between the hero section and Navbar to bring @@ -515,11 +503,6 @@ The website docs analysis is in progess. - Provide intra-site search options such as a search button to make it easier for users to search and find information. -#### Case studies/social proof - -- Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the - website. - #### Maintenance planning - Identify website maintainers on the site and their roles so users know who to diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 4a80db5..c9e640a 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -38,13 +38,9 @@ The top-level documentation recommendations for this project are: - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - - Document TUF installation procedures on a separate page (At the moment, it's - in the spec doc) - Develop quick start and contribution guides for new users - **Content maintainability and creation process** - - Rename the website repo to a recognizable name e.g _TUF-ReadTheDocs_ or - similar - Add search functionality to the website to make it easier to find content - Identify maintainers for the website repo - Add labels to the website repo @@ -55,8 +51,6 @@ The top-level documentation recommendations for this project are: - Include communication channels on the website repo README - Provide information about project meetings e.g a meeting link and calendar on both the website and repo - - Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the - website. ## Implementation @@ -69,14 +63,11 @@ makes information hard to find and can be confusing to new users. Much of the information on the website can go under a _Docs_ section. Consider the following structure: -- **About**: Overview of TUF project -- **Documentation**: +- **Home page**: Introduction to TUF project +- **Documentation**: Overview of TUF - - Introduction to TUF - TUF project components - - Getting started: TUF Specification, Standardization, reference - implementation, and documentation. You can include installation guides for - each component in this section + - Getting started: Adopters and contributors - Tutorials - Implementations - Best practices From 117e3cdabd013dd1421a0435ca3b4160515d83c6 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 20:28:47 +0000 Subject: [PATCH 48/96] fix formating Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 0d38b9c..ab90207 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -368,8 +368,8 @@ Scale: #### Project governance documentation - The project governance is well documented on the website. There's sufficient - informtaion about it's history including leaders, maintainers and - contributors. However, this information is not visisble in the docs repo + information about it's history including leaders, maintainers and + contributors. However, this information is not visible in the docs repo README. ### Contributor recommendations From 5e8218844b2eb455a3724af119a71adf426c16ae Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 20 Jul 2024 17:02:38 +0000 Subject: [PATCH 49/96] Edit website docs structure Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index c9e640a..6511aa4 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -63,14 +63,18 @@ makes information hard to find and can be confusing to new users. Much of the information on the website can go under a _Docs_ section. Consider the following structure: -- **Home page**: Introduction to TUF project +- **Home page** - **Documentation**: Overview of TUF - - TUF project components - Getting started: Adopters and contributors - - Tutorials + - Project :Tap,History,Timeline + - Metadata + - Adoptions - Implementations + - Security audits + - Enhancement proposals - Best practices + - FAQ - **Community**: You can have two sections. From fb0aa0f62fe6be91ee947048c8dd0d7b8348f73d Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 20 Jul 2024 19:10:49 +0000 Subject: [PATCH 50/96] create issues documentation foor TUF Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 2 +- analyses/0012-TUF/issues.md | 125 ++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 6511aa4..17ad8f8 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -151,7 +151,7 @@ _#docs \#Goodfirstissue_ to make it easier for contributors to get started. Develop contributor guides to assist new contributors to get started. -### Create procedures for developing the docs site locally +### Create procedures for developing the website locally Develop procedures for developing the docs site locally i.e. cloning, building, and serving the documentation. You can also provide information about the tools diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index e69de29..972f10a 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -0,0 +1,125 @@ +--- +title: TUF Issue +tags: TUF +--- + +## Overview + +This issue tracks recommended changes resulting from an analysis of the TUF +documentation commissioned by CNCF. The analysis and supporting documents are +here: under +`0012-TUF`.This is a master list of issues recommended in the TUF tech doc +analysis and implementation plan. + +## Issues + +### Reorganize website content + +Reorganize website content by introducing new sections and consolidating some +pages. For example, a docs section can accomodate most pages on the website. +View the proposed outline in the [Implementation document](./implementation.md) + +This proposed change consolidates related pages and removes others, chnaging the +structure of the current website +[theupdateframework.io](https://theupdateframework.io/) + +Audience: Admin + +Type: Conceptual + +### Categorize new user information according to user roles + +Structure the _Getting Started_ section according to user roles. The identified +user roles are _Adopters_ and _Contributors_. + +These can be further broken down into subsections depending on use case. View +the [Implementation document](./implementation.md) to understand the user roles +and the kind of information targeting each role. + +You can add an _Edit this page_ button on website and link it to the doc +repository for doc contributors. + +Audience: Admin + +Type: Conseptual + +### Introduce Instructional material for user roles + +Create instructional material in the _Getting Started_ section for each user +role i.e configuration guides and tutorials. Include links to the GitHub repos +associated with each role. + +Audience: Developer + +Type: Task + +### Add README to website repo + +Add a README to the website repo with information about the project. You can +provide an overview of the project, links to other project repos, communication +channels, contributors' guide and a link to the deployed website on the _About_ +section on GitHub. + +This provides comprehensive information for anyone coming across the repo on +GitHub. + +Audience: Contributor/Admin + +Type: Conceptual + +### Add search functionality to website + +Though not priority, a search functionality helps users easily navigate the +website. The proposed Docsy theme has a search functionality that easy to adopt. + +Audience: Developer + +Type: Task + +### Identify maintainers for website repo + +Identify maintainers on the website repo both on the website and repo to make it +easier for contributors to contact them. This information can be added to the +Readme + +Audience: Admin + +Type: Conceptual + +### Add labels to the website repo + +Add labels to issues in the website repo to make it easier for contributors to +identify suitable issues. Labels such as _#docs \#Goodfirstissue_ make it easier +for contributors to get started. + +Audience: Admin + +Type: Task + +### Develop a guidelines contributors on website repo + +Develop contributor guides to assist new contributors to get started. + +Audience: Admin + +Type: Task + +### Create procedures for developing the website locally + +Provide procedures for developing the docs site locally i.e. cloning, building, +and serving the website. You can also provide information about the tools used +to build and maintain the site e.g :Hugo site, Docsy theme, served on Netlify. + +Audience: Contributor + +Type: Task + +### Provide project meeting details and calendar on website repo + +Information on the communication channels on the +[Community repo](https://github.com/theupdateframework/community) can be also +added to the deployed website and the website repo. + +Audience: Contributor + +Type: Task From ff2a044c70f81121b6b0faa882d292b8d7375032 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 22 Jul 2024 07:46:40 +0000 Subject: [PATCH 51/96] Update users roles subsections in implementation and issue docs Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 2 ++ analyses/0012-TUF/issues.md | 14 +++++++++++--- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 17ad8f8..3c7b673 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -115,6 +115,8 @@ Contributors: repository library such as python-tuf, go-tuf, etc.) - **Contributors**: want to contribute either to the spec or documentation. + - Spec contributors + - Docs contributors ## Introduce Instructional Material diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 972f10a..47583a7 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -32,9 +32,17 @@ Type: Conceptual Structure the _Getting Started_ section according to user roles. The identified user roles are _Adopters_ and _Contributors_. -These can be further broken down into subsections depending on use case. View -the [Implementation document](./implementation.md) to understand the user roles -and the kind of information targeting each role. +These can be further broken down into subsections depending on use case: + +- Adopters : + - Client maintainers + - Respository maintainers +- Contributors: + - Spec contributors + - Docs contributors + +View the [Implementation document](./implementation.md) to understand the user +roles and the kind of information targeting each role. You can add an _Edit this page_ button on website and link it to the doc repository for doc contributors. From e558ef08784a01fdc3ee200349869bc190d704a7 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 22 Jul 2024 08:19:13 +0000 Subject: [PATCH 52/96] Add README Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index e69de29..e0146f5 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -0,0 +1,22 @@ +# README + +This section contains analysis of The Update Framework (TUF) project +documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group +process aimed at assisting cloud-native open-source projects with their +documentation efforts. + +The documents therein provide an analysis of +[TUF](https://github.com/theupdateframework/theupdateframework.io) existing +website documentation as of June 2024.There are suggested recommendations for +implementation and a list of GitHub Issues. Use the following list to view each +document: + +- [TUF Analysis](analysis.md) - Analyzes the existing TUF website documentation + and provides recommendations. + +- [TUF Implementation](implementation.md) - Provides detailed and actionable + recommendations. + +- [TUF Issues](issues.md) - A list of documentation improvements derived from + TUF Implementation, to be entered as issues in the + [theupdateframework.io repo](https://github.com/theupdateframework/theupdateframework.io). From eb5d918fc2995c4f32e61ad8f115989aef84c935 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Thu, 25 Jul 2024 12:37:45 +0000 Subject: [PATCH 53/96] Add analysis table in implemenation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 41 +++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 3c7b673..b04793e 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -168,4 +168,45 @@ and repo. Makes it easier for contributors to sync with their calendars and get notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. +## Proposed Information Architecture for the TUF Website + +| Website | Section | Subsections | +| ------------------------ | --------------- | ------------------------- | +| **Current TUF Website** | Homepage | | +| | About | - Overview | +| | | - History | +| | | - Timeline | +| | | - Project | +| | | - Publications | +| | | - Code of conduct | +| | Getting Started | - Roles and metadata | +| | | - FAQ | +| | | - Specification (latest) | +| | | - Specification index | +| | | - Implementations | +| | | - Videos | +| | Community | - Adoptions | +| | | - Reporting issues | +| | | - Security audits | +| | | - Proposals | +| | | - Contribute | +| | | - Chat(CNCF Slack) | +| | News | | +| | Contact | | +| **Proposed TUF website** | Homepage | | +| | Docs | - Overview | +| | | - History | +| | | - Timeline | +| | | - Project (Tap, metadata) | +| | | - Security audits | +| | | - Adoptions | +| | | - FAQ | +| | Community | - Code of conduct | +| | | - Learn and connect | +| | | - Develop and contribute | +| | Resources | - News | +| | | - Publications and press | +| | | - Videos | +| | | | + [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 From 4c99e48ac630d583b7bf83a3c9cd4aa75224fe71 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Thu, 25 Jul 2024 12:38:42 +0000 Subject: [PATCH 54/96] Addd heading to IA table in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index b04793e..3c16ac2 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -169,6 +169,7 @@ notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. ## Proposed Information Architecture for the TUF Website +The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. | Website | Section | Subsections | | ------------------------ | --------------- | ------------------------- | From 32b98e1606b8415ffe876237327ef64d19275f21 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 20:25:51 +0300 Subject: [PATCH 55/96] Update analyses/0012-TUF/README.md Co-authored-by: Patrice Chalin Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index e0146f5..4733c9c 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,4 +1,6 @@ -# README +# TUF Documentation Analysis + +**Status: Draft** This section contains analysis of The Update Framework (TUF) project documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group From 609d8b37b3ae8f5f06869f70288dbc7861587c67 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 20:51:39 +0300 Subject: [PATCH 56/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index ab90207..720ca7a 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -334,7 +334,7 @@ Scale: #### Communication methods documented -- Information about the TUF **slack channel** is available on the website on +- Information about the TUF **slack channel** is available on the website in both the Community and Contact sections. However,this information should be visible on the website repo README for easy access. From 10b1776d66b1a5d7eee46a75f16e2996440f02d1 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 18:15:24 +0000 Subject: [PATCH 57/96] Remove gitpod.yml Signed-off-by: Dindihub Dindi --- .gitignore | 1 + .gitpod.yml | 8 -------- analyses/0012-TUF/analysis.md | 17 +++++++++++------ analyses/0012-TUF/implementation.md | 5 ++++- 4 files changed, 16 insertions(+), 15 deletions(-) delete mode 100644 .gitpod.yml diff --git a/.gitignore b/.gitignore index 7807fd3..16fb088 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ # npm assets node_modules/ package-lock.json +.gitpod.yml \ No newline at end of file diff --git a/.gitpod.yml b/.gitpod.yml deleted file mode 100644 index 0814e55..0000000 --- a/.gitpod.yml +++ /dev/null @@ -1,8 +0,0 @@ -# This configuration file was automatically generated by Gitpod. -# Please adjust to your needs (see https://www.gitpod.io/docs/introduction/learn-gitpod/gitpod-yaml) -# and commit this file to your remote git repository to share the goodness with others. - -# Learn more from ready-to-use templates: https://www.gitpod.io/docs/introduction/getting-started/quickstart - -tasks: - - init: npm install diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index ab90207..391da5e 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -61,6 +61,11 @@ is stored on the TUF GitHub repo. - TUF Augmentation proposals repository: +- python-tuf: +- go-tuf: +- tuf-on-ci: + +- RSTUF: ### How this document is organized @@ -238,17 +243,17 @@ Scale: _Aborted_ is used in the [Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time) -- There is no use of abliest language like simple,easy in the documentation. +- There is no use of abliest language like simple, or easy in the documentation. ### Project recommendations #### Information architecture -- Information can be re-organized on the website to better the workflow. That - is, each section can contain only related information. For example, introduce - a documentation section to consolidate other pages on the site. Much of the - information in the _About_ and _Getting started_ sections can go under a - _Docs_ section +- Information can be re-organized on the website to make it easier for new users + to navigate. That is, each section can contain only related information. For + example, introduce a documentation section to consolidate other pages on the + site. Much of the information in the _About_ and _Getting started_ sections + can go under a _Docs_ section - Provide step-by-step tutorials for users on a separate page and label it as such. diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 3c16ac2..9078e98 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -169,7 +169,10 @@ notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. ## Proposed Information Architecture for the TUF Website -The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. + +The table below outlines the current information architecture(IA) of the +[TUF website](https://theupdateframework.io/) and the proposed IA for the new +website. | Website | Section | Subsections | | ------------------------ | --------------- | ------------------------- | From 361a2dcd56146f443c4636d02a0b48c437473bc4 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 18:27:21 +0000 Subject: [PATCH 58/96] Fix markdown issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index 4733c9c..9ea637a 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,6 +1,6 @@ # TUF Documentation Analysis -**Status: Draft** +[Context: "Status: Draft"] This section contains analysis of The Update Framework (TUF) project documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group From b9bbd7d4ef1d3fd9ad77571344d8151e0f8b5aaa Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 21:47:59 +0300 Subject: [PATCH 59/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 1ca25ae..5813f36 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -348,7 +348,7 @@ Scale: [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file) - Information about the mailing list is included in the documentation. There's - no information about project meetings. Instead the users are directed to join + no information about project meetings. Instead, the users are directed to join the #TUF channel on CNCF slack. #### Beginner friendly issue backlog From a4dd60f726094d90843edd848fc3b620af6f06a8 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 21:51:27 +0300 Subject: [PATCH 60/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 5813f36..0a078e0 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -386,7 +386,7 @@ Scale: [theupdateframework](https://github.com/theupdateframework) that lists all TUF repositories. - Include communication channels on the Docs repo README for visibility. -- Provide information about project meetings e.g a meeting link and calendar. +- Provide information about project meetings, e.g., a meeting link and calendar. #### Beginner friendly issue backlog From 1d795d58c7302764391c9190f2ba22f73ea39d13 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 19:03:56 +0000 Subject: [PATCH 61/96] Resolve comments Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 1ca25ae..f670999 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -334,7 +334,7 @@ Scale: - The documentation repo issues do not appear to be maintained. There are old issues that are still open which may confuse contributors looking for issues to work on. -- Issues do not have labels making it hard for contributors to identify suitable +- Information about the TUF **slack channel** is available on the website in areas of interest #### Communication methods documented @@ -343,7 +343,7 @@ Scale: both the Community and Contact sections. However,this information should be visible on the website repo README for easy access. -- The repo link on the website does not point to the documentation but rather + no information about project meetings. Instead, the users are directed to join the [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file) @@ -381,18 +381,18 @@ Scale: #### Communication methods documented -- The website repo link may be included on the site as an entry point for the +- Provide information about project meetings, e.g., a meeting link and calendar. project or the umbrella repo [theupdateframework](https://github.com/theupdateframework) that lists all TUF repositories. -- Include communication channels on the Docs repo README for visibility. +- Maintain issues, track, close, and stale old issues to reduce backlog. - Provide information about project meetings e.g a meeting link and calendar. #### Beginner friendly issue backlog - Maintain issues, track,close and stale old issues to reduce backlog. -- Label all issues to assist new users and contributors identify areas of - interest. +- Include instructions on how to contribute to a CONTRIBUTING guideline, e.g., + how interest. #### New contributor getting started content @@ -433,12 +433,14 @@ Scale: 4 = Meets or exceeds standards -5 = Exemplary +- There's no guideline or tutorial to assist users in generating the website + from 5 = Exemplary ### Summary of Issues -- There's no guideline or tutorial to assist users to generate the website from - the website repo. +navigation option is a menu bar. This makes it difficult to find information. +the website repo. + - Information about the website build, tools and how to generate it are not available on the website or the docs repo. - Intra-site search mechanism is not available from the website. The only @@ -460,7 +462,7 @@ The website docs analysis is in progress. - The website follows a mobile-first design with all pages, menu's and features visible on smaller screens. -- Website pages are readable +- There's a recognizable brand for the project, a logo, and a blue-white color - The website does not provide a text-to-speech option for users. #### Branding and design From ff681034861f5665d4d1892a63e19b9016053ac9 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 29 Jul 2024 07:46:18 +0000 Subject: [PATCH 62/96] Add suggested improvements to implementation and issue docs Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 2 +- analyses/0012-TUF/implementation.md | 105 +++++++++++++++------------- analyses/0012-TUF/issues.md | 18 +++++ 3 files changed, 77 insertions(+), 48 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 502bca9..9315c6e 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -397,7 +397,7 @@ Scale: #### New contributor getting started content - Include instructions on how to contribute on a CONTRIBUTING guideline e.g how - to identify issues,forking,cloning, and submitting PRs. + to identify issues, forking, cloning, and submitting PRs. #### Project governance documentation diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 9078e98..84e93c5 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -66,14 +66,13 @@ structure: - **Home page** - **Documentation**: Overview of TUF - - Getting started: Adopters and contributors - - Project :Tap,History,Timeline + - Getting started: Adopters, contributors, Timeline, and History + - Project - Metadata + - Enhancement proposals - Adoptions - Implementations - Security audits - - Enhancement proposals - - Best practices - FAQ - **Community**: You can have two sections. @@ -118,6 +117,17 @@ Contributors: - Spec contributors - Docs contributors +## Add introductory Video to homepage + +- Add a 1 minute video covering an overview of the TUF project why the project + matters. + +## Add a 'Schedule and appointment' icon to the website + +- Create 'Schedule an appointment' link on the website. This creates an avenue + for users to talk to community members to learn the project or seek + clarification. + ## Introduce Instructional Material - Identify user roles in the documentation and what can be achieved by each @@ -155,11 +165,11 @@ Develop contributor guides to assist new contributors to get started. ### Create procedures for developing the website locally -Develop procedures for developing the docs site locally i.e. cloning, building, -and serving the documentation. You can also provide information about the tools -used to build and maintain the site. When such information is available it helps -contributors know how to improve the website. You might get some good -suggestions. +Develop procedures for developing the website site locally i.e. cloning, +building, and serving the documentation. You can also provide information about +the tools used to build and maintain the site. When such information is +available it helps contributors know how to improve the website. You might get +some good suggestions. ### Provide project meeting links and calendar @@ -174,43 +184,44 @@ The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. -| Website | Section | Subsections | -| ------------------------ | --------------- | ------------------------- | -| **Current TUF Website** | Homepage | | -| | About | - Overview | -| | | - History | -| | | - Timeline | -| | | - Project | -| | | - Publications | -| | | - Code of conduct | -| | Getting Started | - Roles and metadata | -| | | - FAQ | -| | | - Specification (latest) | -| | | - Specification index | -| | | - Implementations | -| | | - Videos | -| | Community | - Adoptions | -| | | - Reporting issues | -| | | - Security audits | -| | | - Proposals | -| | | - Contribute | -| | | - Chat(CNCF Slack) | -| | News | | -| | Contact | | -| **Proposed TUF website** | Homepage | | -| | Docs | - Overview | -| | | - History | -| | | - Timeline | -| | | - Project (Tap, metadata) | -| | | - Security audits | -| | | - Adoptions | -| | | - FAQ | -| | Community | - Code of conduct | -| | | - Learn and connect | -| | | - Develop and contribute | -| | Resources | - News | -| | | - Publications and press | -| | | - Videos | -| | | | +| Website | Section | Subsections | +| ------------------------ | --------------- | ------------------------ | --- | +| **Current TUF Website** | Homepage | | +| | About | - Overview | +| | | - History | +| | | - Timeline | +| | | - Project | +| | | - Publications | +| | | - Code of conduct | +| | Getting Started | - Roles and metadata | +| | | - FAQ | +| | | - Specification (latest) | +| | | - Specification index | +| | | - Implementations | +| | | - Videos | +| | Community | - Adoptions | +| | | - Reporting issues | +| | | - Security audits | +| | | - Proposals | +| | | - Contribute | +| | | - Chat(CNCF Slack) | +| | News | | +| | Contact | | +| **Proposed TUF website** | Homepage | | +| | Docs | - Overview | +| | | - Project | +| | | - Enhancement proposals | +| | | - Metadata | +| | | - Getting started | | +| | | - Security audits | +| | | - Adoptions | +| | | - FAQ | +| | Community | - Code of conduct | +| | | - Learn and connect | +| | | - Develop and contribute | +| | Resources | - News | +| | | - Publications and press | +| | | - Videos | +| | | | [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 47583a7..898fc71 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -51,6 +51,24 @@ Audience: Admin Type: Conseptual +### Add introductory Video to homepage + +- Add a 1 minute video covering an overview of the TUF project why the project + matters. + +Audience: Admin + +Type: Conseptual + +### Add a 'Schedule and appointment' icon to the website + +- Create a 'Schedule an appointment' link on the website footer section. It can + also appear on the community page. + +Audience: Admin + +Type: Conseptual + ### Introduce Instructional material for user roles Create instructional material in the _Getting Started_ section for each user From 179b614f6a052b5267c7cdbea5e941b3ca24050b Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 17 Jul 2024 20:54:29 +0300 Subject: [PATCH 63/96] Update analyses/0012-TUF/analysis.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lukas Pühringer Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index fd26647..e4d68e7 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -75,7 +75,7 @@ concern: branding, website structure, and maintainability. Each section begins with summary ratings based on a rubric with appropriate -[criteria] for the section, then proceeds to: +criteria for the section, then proceeds to: - **Comments**: Observations about the existing documentation, with a focus on how it does or does not help TUF project users achieve their goals. From d00ae2c8c2dba93c2b0ad50073bee9b321aaa579 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 17 Jul 2024 20:54:44 +0300 Subject: [PATCH 64/96] Update analyses/0012-TUF/analysis.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lukas Pühringer Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index e4d68e7..8c28c63 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -190,11 +190,9 @@ Scale: - The website repo does not have guides for new users or contributors to get started -- There are no installation guides because TUF is a specification.There are - several TUF libraries (python, go, etc.), which can be used to implement a - TUF-powered repository and client. Also, there are TUF repository applications - (tuf-on-ci, RSTUF), which provide specific but reusable TUF repositories, plus - tooling to use them. +- There isn't any documentation labeled 'Installation guide'. Instead, + installation instructions are part of a larger document labelled + [The Update Framework specification](https://theupdateframework.github.io/specification/latest) - TUF docs do not provide information about application-specific/OS functionality in system updates. Instead the documentation states that TUF From 31a81019428c8a4c6f0ecab0ea33f0b240e7d095 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Wed, 17 Jul 2024 21:05:08 +0300 Subject: [PATCH 65/96] Update analyses/0012-TUF/analysis.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lukas Pühringer Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 8c28c63..ed1ab9c 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -375,7 +375,7 @@ Scale: #### Project governance documentation - The project governance is well documented on the website. There's sufficient - informtaion about it's history including leaders,maintainers and contributors. + informtaion about it's history including leaders, maintainers and contributors. However, this information is not visisble in the docs repo README. ### Contributor recommendations From c7992659b26a40d341e5a81f925c0f210422cb81 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 19:31:54 +0000 Subject: [PATCH 66/96] Fix formatting issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index ed1ab9c..22627f4 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -375,8 +375,9 @@ Scale: #### Project governance documentation - The project governance is well documented on the website. There's sufficient - informtaion about it's history including leaders, maintainers and contributors. - However, this information is not visisble in the docs repo README. + informtaion about it's history including leaders, maintainers and + contributors. However, this information is not visisble in the docs repo + README. ### Contributor recommendations From b4312efaf6aba51e2c58ec7860966d9ee80f858c Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 19:35:57 +0000 Subject: [PATCH 67/96] Edit text in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index e86f570..9c8c9f2 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -105,7 +105,8 @@ the three project components. ### Add user roles to the Getting Started section Structure the _Getting Started_ section according to user roles under a _Docs_ -section. The perceived user roles for this project are: +section. The perceived user roles for this project are Adopters and +Contributors: - **Adopters**: Integrate TUF security properties into new and existing content delivery systems. Adopters can be classified into two categories: From 3661765ebb88c2d197ebd4d93af3360344578a7e Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 19:40:07 +0000 Subject: [PATCH 68/96] Edit text in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 9c8c9f2..4a80db5 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -111,11 +111,11 @@ Contributors: - **Adopters**: Integrate TUF security properties into new and existing content delivery systems. Adopters can be classified into two categories: - - **Client maintainers**: depend on repository maintainers, to provide a TUF + - _Client maintainers_: depend on repository maintainers, to provide a TUF repo. And they can choose from multiple TUF client implementations - (python-tuf, go-tuf, etc.) . Typically, they will pick the language their + (python-tuf, go-tuf, etc.) Typically, they will pick the language their client is written in. - - **Repository maintainers** can either use an existing TUF repository + - _Repository maintainers_: Use either an existing TUF repository implementation (tuf-on-ci, RSTUF), or roll their own (typically using a tuf repository library such as python-tuf, go-tuf, etc.) From da7433d0319fcdca76cbb4e9de05848ef276b2db Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 20:02:18 +0000 Subject: [PATCH 69/96] Edit text in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 47 +++++++++-------------------- analyses/0012-TUF/implementation.md | 15 ++------- 2 files changed, 18 insertions(+), 44 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 22627f4..ef468ca 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -168,9 +168,7 @@ Scale: - There are no tutorials for specific feature implementation. But, there are videos explaining various use cases. -- There aren't specific task-based guides for features. The available guide for - implementing the specification is part of a larger document labelled - [Specification(latest)](https://theupdateframework.github.io/specification/latest) +- There aren't specific task-based guides for features. - There is a FAQ and reporting issues sections for troubleshooting. @@ -250,14 +248,13 @@ Scale: information in the _About_ and _Getting started_ sections can go under a _Docs_ section -- Provide step-by-step tutorials for each use case on a separate page and label - it as such. At the moment all the tutorials are included in a larger document - the _Specification(latest)_ +- Provide step-by-step tutorials for users on a separate page and label it as + such. -- Create a **README** on the documentation repo with information detailing the - content of the repo. Also include a **contribution guide** and information of - how to set up the website and run it locally for new contributors. You can - include a getting started section on the README. +- Create a **README** on the website repo with information detailing the content + of the repo. Also include a **contribution guide** and information of how to + set up the website and run it locally for new contributors. You can include a + getting started section on the README. #### New user content @@ -268,12 +265,6 @@ Scale: - Include a **README** in the documentation repo with a contributor guide on how to get started with Docs. -- Create an _Installation guide_ on a separate page. This can contain - step-to-step instructions for diffent users including beginners. Installation - instructions in the - [The Update Framework specification](https://theupdateframework.github.io/specification/latest) - can be included here. - #### Content maintainability & site mechanics - Include a search button on the website to make it easier for users to search @@ -329,8 +320,8 @@ Scale: ### Summary of Issues - The documentation does not contain information tailored to contributors. -- Information about TUF communication channels is not visible in the docs repo. - But the information is available on the website. +- Information about TUF communication channels is not visible in the website + repo. But the information is available on the website. - The documentation does not contain information about other project repos and their links. Making it harder for contributors to find them. - The documentation repo issues do not appear to be maintained. There are old @@ -343,7 +334,7 @@ Scale: - Information about the TUF **slack channel** is available on the website on both the Community and Contact sections. However,this information should be - visible on the doc repo README for easy access. + visible on the website repo README for easy access. - The repo link on the website does not point to the documentation but rather the @@ -383,8 +374,10 @@ Scale: #### Communication methods documented -- The documentation repo link may be included on the site as an entry point for - the project. The repo can then include information about other repos. +- The website repo link may be included on the site as an entry point for the + project or the umbrella repo + [theupdateframework](https://github.com/theupdateframework) that lists all TUF + repositories. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings e.g a meeting link and calendar. @@ -454,7 +447,7 @@ Scale: #### Minimal website requirements -The website docs analysis is in progess. +The website docs analysis is in progress. #### Usability, accessibility and devices @@ -497,11 +490,6 @@ The website docs analysis is in progess. ### Website recommendations -#### Single-source requirement - -- Rename the website repo _theupdateframework.io_ to a name that reflect it's - content, e.g., _TUFwebsite.io_. It makes it easier to find. - #### Branding and design - Reduce the empty space between the hero section and Navbar to bring @@ -513,11 +501,6 @@ The website docs analysis is in progess. - Provide intra-site search options such as a search button to make it easier for users to search and find information. -#### Case studies/social proof - -- Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the - website. - #### Maintenance planning - Identify website maintainers on the site and their roles so users know who to diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 4a80db5..c9e640a 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -38,13 +38,9 @@ The top-level documentation recommendations for this project are: - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - - Document TUF installation procedures on a separate page (At the moment, it's - in the spec doc) - Develop quick start and contribution guides for new users - **Content maintainability and creation process** - - Rename the website repo to a recognizable name e.g _TUF-ReadTheDocs_ or - similar - Add search functionality to the website to make it easier to find content - Identify maintainers for the website repo - Add labels to the website repo @@ -55,8 +51,6 @@ The top-level documentation recommendations for this project are: - Include communication channels on the website repo README - Provide information about project meetings e.g a meeting link and calendar on both the website and repo - - Add the [TUF blog](https://theupdateframework.github.io/python-tuf) to the - website. ## Implementation @@ -69,14 +63,11 @@ makes information hard to find and can be confusing to new users. Much of the information on the website can go under a _Docs_ section. Consider the following structure: -- **About**: Overview of TUF project -- **Documentation**: +- **Home page**: Introduction to TUF project +- **Documentation**: Overview of TUF - - Introduction to TUF - TUF project components - - Getting started: TUF Specification, Standardization, reference - implementation, and documentation. You can include installation guides for - each component in this section + - Getting started: Adopters and contributors - Tutorials - Implementations - Best practices From d11ea25920f9df3cda19119cc4478ed22065f6f1 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 20:28:47 +0000 Subject: [PATCH 70/96] fix formating Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index ef468ca..3ad3a6b 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -366,8 +366,8 @@ Scale: #### Project governance documentation - The project governance is well documented on the website. There's sufficient - informtaion about it's history including leaders, maintainers and - contributors. However, this information is not visisble in the docs repo + information about it's history including leaders, maintainers and + contributors. However, this information is not visible in the docs repo README. ### Contributor recommendations From 876d5c7fae9dae36206b25a6f1177f4ca9902fe2 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 20 Jul 2024 17:02:38 +0000 Subject: [PATCH 71/96] Edit website docs structure Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index c9e640a..6511aa4 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -63,14 +63,18 @@ makes information hard to find and can be confusing to new users. Much of the information on the website can go under a _Docs_ section. Consider the following structure: -- **Home page**: Introduction to TUF project +- **Home page** - **Documentation**: Overview of TUF - - TUF project components - Getting started: Adopters and contributors - - Tutorials + - Project :Tap,History,Timeline + - Metadata + - Adoptions - Implementations + - Security audits + - Enhancement proposals - Best practices + - FAQ - **Community**: You can have two sections. From edf7d7ab2148e8b9c3fcc888572875f6bae5f5f6 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 20 Jul 2024 19:10:49 +0000 Subject: [PATCH 72/96] create issues documentation foor TUF Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 2 +- analyses/0012-TUF/issues.md | 125 ++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 6511aa4..17ad8f8 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -151,7 +151,7 @@ _#docs \#Goodfirstissue_ to make it easier for contributors to get started. Develop contributor guides to assist new contributors to get started. -### Create procedures for developing the docs site locally +### Create procedures for developing the website locally Develop procedures for developing the docs site locally i.e. cloning, building, and serving the documentation. You can also provide information about the tools diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index e69de29..972f10a 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -0,0 +1,125 @@ +--- +title: TUF Issue +tags: TUF +--- + +## Overview + +This issue tracks recommended changes resulting from an analysis of the TUF +documentation commissioned by CNCF. The analysis and supporting documents are +here: under +`0012-TUF`.This is a master list of issues recommended in the TUF tech doc +analysis and implementation plan. + +## Issues + +### Reorganize website content + +Reorganize website content by introducing new sections and consolidating some +pages. For example, a docs section can accomodate most pages on the website. +View the proposed outline in the [Implementation document](./implementation.md) + +This proposed change consolidates related pages and removes others, chnaging the +structure of the current website +[theupdateframework.io](https://theupdateframework.io/) + +Audience: Admin + +Type: Conceptual + +### Categorize new user information according to user roles + +Structure the _Getting Started_ section according to user roles. The identified +user roles are _Adopters_ and _Contributors_. + +These can be further broken down into subsections depending on use case. View +the [Implementation document](./implementation.md) to understand the user roles +and the kind of information targeting each role. + +You can add an _Edit this page_ button on website and link it to the doc +repository for doc contributors. + +Audience: Admin + +Type: Conseptual + +### Introduce Instructional material for user roles + +Create instructional material in the _Getting Started_ section for each user +role i.e configuration guides and tutorials. Include links to the GitHub repos +associated with each role. + +Audience: Developer + +Type: Task + +### Add README to website repo + +Add a README to the website repo with information about the project. You can +provide an overview of the project, links to other project repos, communication +channels, contributors' guide and a link to the deployed website on the _About_ +section on GitHub. + +This provides comprehensive information for anyone coming across the repo on +GitHub. + +Audience: Contributor/Admin + +Type: Conceptual + +### Add search functionality to website + +Though not priority, a search functionality helps users easily navigate the +website. The proposed Docsy theme has a search functionality that easy to adopt. + +Audience: Developer + +Type: Task + +### Identify maintainers for website repo + +Identify maintainers on the website repo both on the website and repo to make it +easier for contributors to contact them. This information can be added to the +Readme + +Audience: Admin + +Type: Conceptual + +### Add labels to the website repo + +Add labels to issues in the website repo to make it easier for contributors to +identify suitable issues. Labels such as _#docs \#Goodfirstissue_ make it easier +for contributors to get started. + +Audience: Admin + +Type: Task + +### Develop a guidelines contributors on website repo + +Develop contributor guides to assist new contributors to get started. + +Audience: Admin + +Type: Task + +### Create procedures for developing the website locally + +Provide procedures for developing the docs site locally i.e. cloning, building, +and serving the website. You can also provide information about the tools used +to build and maintain the site e.g :Hugo site, Docsy theme, served on Netlify. + +Audience: Contributor + +Type: Task + +### Provide project meeting details and calendar on website repo + +Information on the communication channels on the +[Community repo](https://github.com/theupdateframework/community) can be also +added to the deployed website and the website repo. + +Audience: Contributor + +Type: Task From d113ffb8198dcd690d3810f2ac9b956268fa7b42 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 22 Jul 2024 07:46:40 +0000 Subject: [PATCH 73/96] Update users roles subsections in implementation and issue docs Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 2 ++ analyses/0012-TUF/issues.md | 14 +++++++++++--- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 17ad8f8..3c7b673 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -115,6 +115,8 @@ Contributors: repository library such as python-tuf, go-tuf, etc.) - **Contributors**: want to contribute either to the spec or documentation. + - Spec contributors + - Docs contributors ## Introduce Instructional Material diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 972f10a..47583a7 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -32,9 +32,17 @@ Type: Conceptual Structure the _Getting Started_ section according to user roles. The identified user roles are _Adopters_ and _Contributors_. -These can be further broken down into subsections depending on use case. View -the [Implementation document](./implementation.md) to understand the user roles -and the kind of information targeting each role. +These can be further broken down into subsections depending on use case: + +- Adopters : + - Client maintainers + - Respository maintainers +- Contributors: + - Spec contributors + - Docs contributors + +View the [Implementation document](./implementation.md) to understand the user +roles and the kind of information targeting each role. You can add an _Edit this page_ button on website and link it to the doc repository for doc contributors. From 6fb2e79f41836d1308e9ae4a1f0349ccd97dba7a Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 22 Jul 2024 08:19:13 +0000 Subject: [PATCH 74/96] Add README Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index e69de29..e0146f5 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -0,0 +1,22 @@ +# README + +This section contains analysis of The Update Framework (TUF) project +documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group +process aimed at assisting cloud-native open-source projects with their +documentation efforts. + +The documents therein provide an analysis of +[TUF](https://github.com/theupdateframework/theupdateframework.io) existing +website documentation as of June 2024.There are suggested recommendations for +implementation and a list of GitHub Issues. Use the following list to view each +document: + +- [TUF Analysis](analysis.md) - Analyzes the existing TUF website documentation + and provides recommendations. + +- [TUF Implementation](implementation.md) - Provides detailed and actionable + recommendations. + +- [TUF Issues](issues.md) - A list of documentation improvements derived from + TUF Implementation, to be entered as issues in the + [theupdateframework.io repo](https://github.com/theupdateframework/theupdateframework.io). From e377f22cb3f0b6c8d01ee7d9a6482765daed0a14 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Thu, 25 Jul 2024 12:37:45 +0000 Subject: [PATCH 75/96] Add analysis table in implemenation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 41 +++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 3c7b673..b04793e 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -168,4 +168,45 @@ and repo. Makes it easier for contributors to sync with their calendars and get notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. +## Proposed Information Architecture for the TUF Website + +| Website | Section | Subsections | +| ------------------------ | --------------- | ------------------------- | +| **Current TUF Website** | Homepage | | +| | About | - Overview | +| | | - History | +| | | - Timeline | +| | | - Project | +| | | - Publications | +| | | - Code of conduct | +| | Getting Started | - Roles and metadata | +| | | - FAQ | +| | | - Specification (latest) | +| | | - Specification index | +| | | - Implementations | +| | | - Videos | +| | Community | - Adoptions | +| | | - Reporting issues | +| | | - Security audits | +| | | - Proposals | +| | | - Contribute | +| | | - Chat(CNCF Slack) | +| | News | | +| | Contact | | +| **Proposed TUF website** | Homepage | | +| | Docs | - Overview | +| | | - History | +| | | - Timeline | +| | | - Project (Tap, metadata) | +| | | - Security audits | +| | | - Adoptions | +| | | - FAQ | +| | Community | - Code of conduct | +| | | - Learn and connect | +| | | - Develop and contribute | +| | Resources | - News | +| | | - Publications and press | +| | | - Videos | +| | | | + [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 From 103c89a2c764e6c72051c6fb346607db72da75d0 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Thu, 25 Jul 2024 12:38:42 +0000 Subject: [PATCH 76/96] Addd heading to IA table in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index b04793e..3c16ac2 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -169,6 +169,7 @@ notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. ## Proposed Information Architecture for the TUF Website +The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. | Website | Section | Subsections | | ------------------------ | --------------- | ------------------------- | From 32f36b872ed93572cadc01e49d5f34f66a58ee53 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 18:15:24 +0000 Subject: [PATCH 77/96] Remove gitpod.yml Signed-off-by: Dindihub Dindi --- .gitignore | 1 + .gitpod.yml | 8 -------- analyses/0012-TUF/analysis.md | 17 +++++++++++------ analyses/0012-TUF/implementation.md | 5 ++++- 4 files changed, 16 insertions(+), 15 deletions(-) delete mode 100644 .gitpod.yml diff --git a/.gitignore b/.gitignore index 7807fd3..16fb088 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ # npm assets node_modules/ package-lock.json +.gitpod.yml \ No newline at end of file diff --git a/.gitpod.yml b/.gitpod.yml deleted file mode 100644 index 0814e55..0000000 --- a/.gitpod.yml +++ /dev/null @@ -1,8 +0,0 @@ -# This configuration file was automatically generated by Gitpod. -# Please adjust to your needs (see https://www.gitpod.io/docs/introduction/learn-gitpod/gitpod-yaml) -# and commit this file to your remote git repository to share the goodness with others. - -# Learn more from ready-to-use templates: https://www.gitpod.io/docs/introduction/getting-started/quickstart - -tasks: - - init: npm install diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 3ad3a6b..6f27110 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -61,6 +61,11 @@ is stored on the TUF GitHub repo. - TUF Augmentation proposals repository: +- python-tuf: +- go-tuf: +- tuf-on-ci: + +- RSTUF: ### How this document is organized @@ -236,17 +241,17 @@ Scale: _Aborted_ is used in the [Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time) -- There is no use of abliest language like simple,easy in the documentation. +- There is no use of abliest language like simple, or easy in the documentation. ### Project recommendations #### Information architecture -- Information can be re-organized on the website to better the workflow. That - is, each section can contain only related information. For example, introduce - a documentation section to consolidate other pages on the site. Much of the - information in the _About_ and _Getting started_ sections can go under a - _Docs_ section +- Information can be re-organized on the website to make it easier for new users + to navigate. That is, each section can contain only related information. For + example, introduce a documentation section to consolidate other pages on the + site. Much of the information in the _About_ and _Getting started_ sections + can go under a _Docs_ section - Provide step-by-step tutorials for users on a separate page and label it as such. diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 3c16ac2..9078e98 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -169,7 +169,10 @@ notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. ## Proposed Information Architecture for the TUF Website -The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. + +The table below outlines the current information architecture(IA) of the +[TUF website](https://theupdateframework.io/) and the proposed IA for the new +website. | Website | Section | Subsections | | ------------------------ | --------------- | ------------------------- | From 7da336bfb843b11d5ccad44f400b4e0e19dd676e Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 20:25:51 +0300 Subject: [PATCH 78/96] Update analyses/0012-TUF/README.md Co-authored-by: Patrice Chalin Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index e0146f5..4733c9c 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,4 +1,6 @@ -# README +# TUF Documentation Analysis + +**Status: Draft** This section contains analysis of The Update Framework (TUF) project documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group From 0e1f92d9c9fcc10b4b8d165e35886ecc0fd00c96 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 20:51:39 +0300 Subject: [PATCH 79/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 6f27110..cc103b7 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -337,7 +337,7 @@ Scale: #### Communication methods documented -- Information about the TUF **slack channel** is available on the website on +- Information about the TUF **slack channel** is available on the website in both the Community and Contact sections. However,this information should be visible on the website repo README for easy access. From de126581bd98231c5331dd998fa0bfe400b535cc Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 18:27:21 +0000 Subject: [PATCH 80/96] Fix markdown issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index 4733c9c..9ea637a 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,6 +1,6 @@ # TUF Documentation Analysis -**Status: Draft** +[Context: "Status: Draft"] This section contains analysis of The Update Framework (TUF) project documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group From 6d9c7ba7e2532b4d791b48d3848fbd34ec76c23b Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 19:03:56 +0000 Subject: [PATCH 81/96] Resolve comments Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index cc103b7..660186a 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -332,7 +332,7 @@ Scale: - The documentation repo issues do not appear to be maintained. There are old issues that are still open which may confuse contributors looking for issues to work on. -- Issues do not have labels making it hard for contributors to identify suitable +- Information about the TUF **slack channel** is available on the website in areas of interest #### Communication methods documented @@ -341,7 +341,7 @@ Scale: both the Community and Contact sections. However,this information should be visible on the website repo README for easy access. -- The repo link on the website does not point to the documentation but rather + no information about project meetings. Instead, the users are directed to join the [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file) @@ -379,18 +379,18 @@ Scale: #### Communication methods documented -- The website repo link may be included on the site as an entry point for the +- Provide information about project meetings, e.g., a meeting link and calendar. project or the umbrella repo [theupdateframework](https://github.com/theupdateframework) that lists all TUF repositories. -- Include communication channels on the Docs repo README for visibility. +- Maintain issues, track, close, and stale old issues to reduce backlog. - Provide information about project meetings e.g a meeting link and calendar. #### Beginner friendly issue backlog - Maintain issues, track,close and stale old issues to reduce backlog. -- Label all issues to assist new users and contributors identify areas of - interest. +- Include instructions on how to contribute to a CONTRIBUTING guideline, e.g., + how interest. #### New contributor getting started content @@ -431,12 +431,14 @@ Scale: 4 = Meets or exceeds standards -5 = Exemplary +- There's no guideline or tutorial to assist users in generating the website + from 5 = Exemplary ### Summary of Issues -- There's no guideline or tutorial to assist users to generate the website from - the website repo. +navigation option is a menu bar. This makes it difficult to find information. +the website repo. + - Information about the website build, tools and how to generate it are not available on the website or the docs repo. - Intra-site search mechanism is not available from the website. The only @@ -458,7 +460,7 @@ The website docs analysis is in progress. - The website follows a mobile-first design with all pages, menu's and features visible on smaller screens. -- Website pages are readable +- There's a recognizable brand for the project, a logo, and a blue-white color - The website does not provide a text-to-speech option for users. #### Branding and design From 0a9a456242a0d9d230cb17ce28ea56edae179733 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 21:47:59 +0300 Subject: [PATCH 82/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 660186a..1c5c679 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -346,7 +346,7 @@ Scale: [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file) - Information about the mailing list is included in the documentation. There's - no information about project meetings. Instead the users are directed to join + no information about project meetings. Instead, the users are directed to join the #TUF channel on CNCF slack. #### Beginner friendly issue backlog From 8d53bb1bd12e1b158b21faf22861b51ab618c8aa Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 21:51:27 +0300 Subject: [PATCH 83/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 1c5c679..ebbc273 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -385,6 +385,8 @@ Scale: repositories. - Maintain issues, track, close, and stale old issues to reduce backlog. - Provide information about project meetings e.g a meeting link and calendar. +- Include communication channels on the Docs repo README for visibility. +- Provide information about project meetings, e.g., a meeting link and calendar. #### Beginner friendly issue backlog From 8825adf91d67ee862c4805054fa67e74f5b33470 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 29 Jul 2024 07:46:18 +0000 Subject: [PATCH 84/96] Add suggested improvements to implementation and issue docs Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 2 +- analyses/0012-TUF/implementation.md | 105 +++++++++++++++------------- analyses/0012-TUF/issues.md | 18 +++++ 3 files changed, 77 insertions(+), 48 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index ebbc273..659d780 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -397,7 +397,7 @@ Scale: #### New contributor getting started content - Include instructions on how to contribute on a CONTRIBUTING guideline e.g how - to identify issues,forking,cloning, and submitting PRs. + to identify issues, forking, cloning, and submitting PRs. #### Project governance documentation diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 9078e98..84e93c5 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -66,14 +66,13 @@ structure: - **Home page** - **Documentation**: Overview of TUF - - Getting started: Adopters and contributors - - Project :Tap,History,Timeline + - Getting started: Adopters, contributors, Timeline, and History + - Project - Metadata + - Enhancement proposals - Adoptions - Implementations - Security audits - - Enhancement proposals - - Best practices - FAQ - **Community**: You can have two sections. @@ -118,6 +117,17 @@ Contributors: - Spec contributors - Docs contributors +## Add introductory Video to homepage + +- Add a 1 minute video covering an overview of the TUF project why the project + matters. + +## Add a 'Schedule and appointment' icon to the website + +- Create 'Schedule an appointment' link on the website. This creates an avenue + for users to talk to community members to learn the project or seek + clarification. + ## Introduce Instructional Material - Identify user roles in the documentation and what can be achieved by each @@ -155,11 +165,11 @@ Develop contributor guides to assist new contributors to get started. ### Create procedures for developing the website locally -Develop procedures for developing the docs site locally i.e. cloning, building, -and serving the documentation. You can also provide information about the tools -used to build and maintain the site. When such information is available it helps -contributors know how to improve the website. You might get some good -suggestions. +Develop procedures for developing the website site locally i.e. cloning, +building, and serving the documentation. You can also provide information about +the tools used to build and maintain the site. When such information is +available it helps contributors know how to improve the website. You might get +some good suggestions. ### Provide project meeting links and calendar @@ -174,43 +184,44 @@ The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. -| Website | Section | Subsections | -| ------------------------ | --------------- | ------------------------- | -| **Current TUF Website** | Homepage | | -| | About | - Overview | -| | | - History | -| | | - Timeline | -| | | - Project | -| | | - Publications | -| | | - Code of conduct | -| | Getting Started | - Roles and metadata | -| | | - FAQ | -| | | - Specification (latest) | -| | | - Specification index | -| | | - Implementations | -| | | - Videos | -| | Community | - Adoptions | -| | | - Reporting issues | -| | | - Security audits | -| | | - Proposals | -| | | - Contribute | -| | | - Chat(CNCF Slack) | -| | News | | -| | Contact | | -| **Proposed TUF website** | Homepage | | -| | Docs | - Overview | -| | | - History | -| | | - Timeline | -| | | - Project (Tap, metadata) | -| | | - Security audits | -| | | - Adoptions | -| | | - FAQ | -| | Community | - Code of conduct | -| | | - Learn and connect | -| | | - Develop and contribute | -| | Resources | - News | -| | | - Publications and press | -| | | - Videos | -| | | | +| Website | Section | Subsections | +| ------------------------ | --------------- | ------------------------ | --- | +| **Current TUF Website** | Homepage | | +| | About | - Overview | +| | | - History | +| | | - Timeline | +| | | - Project | +| | | - Publications | +| | | - Code of conduct | +| | Getting Started | - Roles and metadata | +| | | - FAQ | +| | | - Specification (latest) | +| | | - Specification index | +| | | - Implementations | +| | | - Videos | +| | Community | - Adoptions | +| | | - Reporting issues | +| | | - Security audits | +| | | - Proposals | +| | | - Contribute | +| | | - Chat(CNCF Slack) | +| | News | | +| | Contact | | +| **Proposed TUF website** | Homepage | | +| | Docs | - Overview | +| | | - Project | +| | | - Enhancement proposals | +| | | - Metadata | +| | | - Getting started | | +| | | - Security audits | +| | | - Adoptions | +| | | - FAQ | +| | Community | - Code of conduct | +| | | - Learn and connect | +| | | - Develop and contribute | +| | Resources | - News | +| | | - Publications and press | +| | | - Videos | +| | | | [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 47583a7..898fc71 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -51,6 +51,24 @@ Audience: Admin Type: Conseptual +### Add introductory Video to homepage + +- Add a 1 minute video covering an overview of the TUF project why the project + matters. + +Audience: Admin + +Type: Conseptual + +### Add a 'Schedule and appointment' icon to the website + +- Create a 'Schedule an appointment' link on the website footer section. It can + also appear on the community page. + +Audience: Admin + +Type: Conseptual + ### Introduce Instructional material for user roles Create instructional material in the _Getting Started_ section for each user From edd9ae29ab4ecf68369bd321cd28d896b34f1c01 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 16:24:54 +0000 Subject: [PATCH 85/96] resolve merge conflicts Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 9 ++++++++- analyses/0012-TUF/implementation.md | 14 ++++++-------- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 659d780..e86c914 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -174,6 +174,7 @@ Scale: videos explaining various use cases. - There aren't specific task-based guides for features. +- There aren't specific task-based guides for features. - There is a FAQ and reporting issues sections for troubleshooting. @@ -339,7 +340,8 @@ Scale: - Information about the TUF **slack channel** is available on the website in both the Community and Contact sections. However,this information should be - visible on the website repo README for easy access. + visible on the website repo README for easy access. visible on the website + repo README for easy access. no information about project meetings. Instead, the users are directed to join the @@ -379,6 +381,11 @@ Scale: #### Communication methods documented +- The website repo link may be included on the site as an entry point for the + project or the umbrella repo + [theupdateframework](https://github.com/theupdateframework) that lists all TUF + repositories. +- Include communication channels on the Docs repo README for visibility. - Provide information about project meetings, e.g., a meeting link and calendar. project or the umbrella repo [theupdateframework](https://github.com/theupdateframework) that lists all TUF diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 84e93c5..0ff6fee 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -66,13 +66,11 @@ structure: - **Home page** - **Documentation**: Overview of TUF - - Getting started: Adopters, contributors, Timeline, and History - - Project - - Metadata - - Enhancement proposals + - Overview: Metadata,Project,Security + - Getting started: Adopters, contributors, + - History + - Timeline - Adoptions - - Implementations - - Security audits - FAQ - **Community**: You can have two sections. @@ -208,12 +206,12 @@ website. | | News | | | | Contact | | | **Proposed TUF website** | Homepage | | -| | Docs | - Overview | +| | Docs | - Overview: | | | | - Project | | | | - Enhancement proposals | | | | - Metadata | -| | | - Getting started | | | | | - Security audits | +| | | - Getting started | | | | | - Adoptions | | | | - FAQ | | | Community | - Code of conduct | From 1d2903162e940f7c4ba5c513d5a4ce40241e8d42 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 16:33:30 +0000 Subject: [PATCH 86/96] resolve merge conflicts Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/issues.md | 126 ++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 898fc71..a95da56 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -149,3 +149,129 @@ added to the deployed website and the website repo. Audience: Contributor Type: Task + +--- +title: TUF Issue +tags: TUF +--- + +## Overview + +This issue tracks recommended changes resulting from an analysis of the TUF +documentation commissioned by CNCF. The analysis and supporting documents are +here: under +`0012-TUF`.This is a master list of issues recommended in the TUF tech doc +analysis and implementation plan. + +## Issues + +### Reorganize website content + +Reorganize website content by introducing new sections and consolidating some +pages. For example, a docs section can accomodate most pages on the website. +View the proposed outline in the [Implementation document](./implementation.md) + +This proposed change consolidates related pages and removes others, chnaging the +structure of the current website +[theupdateframework.io](https://theupdateframework.io/) + +Audience: Admin + +Type: Conceptual + +### Categorize new user information according to user roles + +Structure the _Getting Started_ section according to user roles. The identified +user roles are _Adopters_ and _Contributors_. + +These can be further broken down into subsections depending on use case. View +the [Implementation document](./implementation.md) to understand the user roles +and the kind of information targeting each role. + +You can add an _Edit this page_ button on website and link it to the doc +repository for doc contributors. + +Audience: Admin + +Type: Conseptual + +### Introduce Instructional material for user roles + +Create instructional material in the _Getting Started_ section for each user +role i.e configuration guides and tutorials. Include links to the GitHub repos +associated with each role. + +Audience: Developer + +Type: Task + +### Add README to website repo + +Add a README to the website repo with information about the project. You can +provide an overview of the project, links to other project repos, communication +channels, contributors' guide and a link to the deployed website on the _About_ +section on GitHub. + +This provides comprehensive information for anyone coming across the repo on +GitHub. + +Audience: Contributor/Admin + +Type: Conceptual + +### Add search functionality to website + +Though not priority, a search functionality helps users easily navigate the +website. The proposed Docsy theme has a search functionality that easy to adopt. + +Audience: Developer + +Type: Task + +### Identify maintainers for website repo + +Identify maintainers on the website repo both on the website and repo to make it +easier for contributors to contact them. This information can be added to the +Readme + +Audience: Admin + +Type: Conceptual + +### Add labels to the website repo + +Add labels to issues in the website repo to make it easier for contributors to +identify suitable issues. Labels such as _#docs \#Goodfirstissue_ make it easier +for contributors to get started. + +Audience: Admin + +Type: Task + +### Develop a guidelines contributors on website repo + +Develop contributor guides to assist new contributors to get started. + +Audience: Admin + +Type: Task + +### Create procedures for developing the website locally + +Provide procedures for developing the docs site locally i.e. cloning, building, +and serving the website. You can also provide information about the tools used +to build and maintain the site e.g :Hugo site, Docsy theme, served on Netlify. + +Audience: Contributor + +Type: Task + +### Provide project meeting details and calendar on website repo + +Information on the communication channels on the +[Community repo](https://github.com/theupdateframework/community) can be also +added to the deployed website and the website repo. + +Audience: Contributor + +Type: Task From 7b51c26938032631ca59e98af9c31f37439e965a Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 16:38:07 +0000 Subject: [PATCH 87/96] Resolve merge issues Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 2 ++ analyses/0012-TUF/issues.md | 14 +++++++++++--- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 0ff6fee..0dc31b7 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -125,6 +125,8 @@ Contributors: - Create 'Schedule an appointment' link on the website. This creates an avenue for users to talk to community members to learn the project or seek clarification. + - Spec contributors + - Docs contributors ## Introduce Instructional Material diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index a95da56..f622964 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -184,9 +184,17 @@ Type: Conceptual Structure the _Getting Started_ section according to user roles. The identified user roles are _Adopters_ and _Contributors_. -These can be further broken down into subsections depending on use case. View -the [Implementation document](./implementation.md) to understand the user roles -and the kind of information targeting each role. +These can be further broken down into subsections depending on use case: + +- Adopters : + - Client maintainers + - Respository maintainers +- Contributors: + - Spec contributors + - Docs contributors + +View the [Implementation document](./implementation.md) to understand the user +roles and the kind of information targeting each role. You can add an _Edit this page_ button on website and link it to the doc repository for doc contributors. From fad5bdad42e94f08762c0aa443f46c477935a7f3 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Thu, 25 Jul 2024 12:38:42 +0000 Subject: [PATCH 88/96] Addd heading to IA table in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 0dc31b7..c66dceb 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -179,6 +179,7 @@ notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. ## Proposed Information Architecture for the TUF Website +The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new From 9cf2627e687db7b9135096fd5ce8561db8a95f77 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 18:15:24 +0000 Subject: [PATCH 89/96] Remove gitpod.yml Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index c66dceb..cf7386e 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -179,7 +179,10 @@ notifications about meetings. I like how the [**Meshery**](https://github.com/layer5io/layer5) project has implemented this. ## Proposed Information Architecture for the TUF Website -The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. + +The table below outlines the current information architecture(IA) of the +[TUF website](https://theupdateframework.io/) and the proposed IA for the new +website. The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new From e0b24dbe96ed7723b4e12ea1dada97ee2c6f7ba1 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 19:03:56 +0000 Subject: [PATCH 90/96] Resolve comments Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 0a36915..2abff3e 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -174,10 +174,7 @@ Scale: videos explaining various use cases. - There aren't specific task-based guides for features. -<<<<<<< HEAD - There aren't specific task-based guides for features. -======= ->>>>>>> ff681034861f5665d4d1892a63e19b9016053ac9 - There is a FAQ and reporting issues sections for troubleshooting. @@ -336,6 +333,7 @@ Scale: - The documentation repo issues do not appear to be maintained. There are old issues that are still open which may confuse contributors looking for issues to work on. +- Information about the TUF **slack channel** is available on the website in - Information about the TUF **slack channel** is available on the website in areas of interest @@ -343,12 +341,8 @@ Scale: - Information about the TUF **slack channel** is available on the website in both the Community and Contact sections. However,this information should be -<<<<<<< HEAD visible on the website repo README for easy access. visible on the website repo README for easy access. -======= - visible on the website repo README for easy access. ->>>>>>> ff681034861f5665d4d1892a63e19b9016053ac9 no information about project meetings. Instead, the users are directed to join the @@ -388,17 +382,12 @@ Scale: #### Communication methods documented -<<<<<<< HEAD - The website repo link may be included on the site as an entry point for the -======= -- Provide information about project meetings, e.g., a meeting link and calendar. ->>>>>>> ff681034861f5665d4d1892a63e19b9016053ac9 project or the umbrella repo [theupdateframework](https://github.com/theupdateframework) that lists all TUF repositories. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings, e.g., a meeting link and calendar. -<<<<<<< HEAD project or the umbrella repo [theupdateframework](https://github.com/theupdateframework) that lists all TUF repositories. @@ -406,8 +395,6 @@ Scale: - Provide information about project meetings e.g a meeting link and calendar. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings, e.g., a meeting link and calendar. -======= ->>>>>>> ff681034861f5665d4d1892a63e19b9016053ac9 #### Beginner friendly issue backlog From 5bff9d3dc197d7c7a1ced0044c0794ada2521ceb Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 26 Jul 2024 21:51:27 +0300 Subject: [PATCH 91/96] Update analyses/0012-TUF/analysis.md Co-authored-by: Charles Uneze Signed-off-by: Dindihub <100135497+Dindihub@users.noreply.github.com> --- analyses/0012-TUF/analysis.md | 1 + 1 file changed, 1 insertion(+) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 2abff3e..e2b1bea 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -395,6 +395,7 @@ Scale: - Provide information about project meetings e.g a meeting link and calendar. - Include communication channels on the Docs repo README for visibility. - Provide information about project meetings, e.g., a meeting link and calendar. +- Provide information about project meetings, e.g., a meeting link and calendar. #### Beginner friendly issue backlog From 6a6313b51198c47917ae961a4e08a62be49ad6e5 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 16:56:56 +0000 Subject: [PATCH 92/96] resolve conflict in issues file Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/issues.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index f622964..110f9de 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -203,6 +203,24 @@ Audience: Admin Type: Conseptual +### Add introductory Video to homepage + +- Add a 1 minute video covering an overview of the TUF project why the project + matters. + +Audience: Admin + +Type: Conseptual + +### Add a 'Schedule and appointment' icon to the website + +- Create a 'Schedule an appointment' link on the website footer section. It can + also appear on the community page. + +Audience: Admin + +Type: Conseptual + ### Introduce Instructional material for user roles Create instructional material in the _Getting Started_ section for each user From ef600695228c537ff54ca97f0597cc5d9abf0483 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 17:06:03 +0000 Subject: [PATCH 93/96] resolve merge conflicts Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/issues.md | 154 +----------------------------------- 1 file changed, 1 insertion(+), 153 deletions(-) diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 110f9de..9ffb2b8 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -62,159 +62,7 @@ Type: Conseptual ### Add a 'Schedule and appointment' icon to the website -- Create a 'Schedule an appointment' link on the website footer section. It can - also appear on the community page. - -Audience: Admin - -Type: Conseptual - -### Introduce Instructional material for user roles - -Create instructional material in the _Getting Started_ section for each user -role i.e configuration guides and tutorials. Include links to the GitHub repos -associated with each role. - -Audience: Developer - -Type: Task - -### Add README to website repo - -Add a README to the website repo with information about the project. You can -provide an overview of the project, links to other project repos, communication -channels, contributors' guide and a link to the deployed website on the _About_ -section on GitHub. - -This provides comprehensive information for anyone coming across the repo on -GitHub. - -Audience: Contributor/Admin - -Type: Conceptual - -### Add search functionality to website - -Though not priority, a search functionality helps users easily navigate the -website. The proposed Docsy theme has a search functionality that easy to adopt. - -Audience: Developer - -Type: Task - -### Identify maintainers for website repo - -Identify maintainers on the website repo both on the website and repo to make it -easier for contributors to contact them. This information can be added to the -Readme - -Audience: Admin - -Type: Conceptual - -### Add labels to the website repo - -Add labels to issues in the website repo to make it easier for contributors to -identify suitable issues. Labels such as _#docs \#Goodfirstissue_ make it easier -for contributors to get started. - -Audience: Admin - -Type: Task - -### Develop a guidelines contributors on website repo - -Develop contributor guides to assist new contributors to get started. - -Audience: Admin - -Type: Task - -### Create procedures for developing the website locally - -Provide procedures for developing the docs site locally i.e. cloning, building, -and serving the website. You can also provide information about the tools used -to build and maintain the site e.g :Hugo site, Docsy theme, served on Netlify. - -Audience: Contributor - -Type: Task - -### Provide project meeting details and calendar on website repo - -Information on the communication channels on the -[Community repo](https://github.com/theupdateframework/community) can be also -added to the deployed website and the website repo. - -Audience: Contributor - -Type: Task - ---- -title: TUF Issue -tags: TUF ---- - -## Overview - -This issue tracks recommended changes resulting from an analysis of the TUF -documentation commissioned by CNCF. The analysis and supporting documents are -here: under -`0012-TUF`.This is a master list of issues recommended in the TUF tech doc -analysis and implementation plan. - -## Issues - -### Reorganize website content - -Reorganize website content by introducing new sections and consolidating some -pages. For example, a docs section can accomodate most pages on the website. -View the proposed outline in the [Implementation document](./implementation.md) - -This proposed change consolidates related pages and removes others, chnaging the -structure of the current website -[theupdateframework.io](https://theupdateframework.io/) - -Audience: Admin - -Type: Conceptual - -### Categorize new user information according to user roles - -Structure the _Getting Started_ section according to user roles. The identified -user roles are _Adopters_ and _Contributors_. - -These can be further broken down into subsections depending on use case: - -- Adopters : - - Client maintainers - - Respository maintainers -- Contributors: - - Spec contributors - - Docs contributors - -View the [Implementation document](./implementation.md) to understand the user -roles and the kind of information targeting each role. - -You can add an _Edit this page_ button on website and link it to the doc -repository for doc contributors. - -Audience: Admin - -Type: Conseptual - -### Add introductory Video to homepage - -- Add a 1 minute video covering an overview of the TUF project why the project - matters. - -Audience: Admin - -Type: Conseptual - -### Add a 'Schedule and appointment' icon to the website - -- Create a 'Schedule an appointment' link on the website footer section. It can +- Create a _Schedule an appointment_ link on the website footer section. It can also appear on the community page. Audience: Admin From 595ecbc263e9ea4c08b588cf3b8d434beb8be8b3 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 7 Aug 2024 18:40:48 +0000 Subject: [PATCH 94/96] fix table structure in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index cf7386e..c5fa71d 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -184,12 +184,8 @@ The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. -The table below outlines the current information architecture(IA) of the -[TUF website](https://theupdateframework.io/) and the proposed IA for the new -website. - | Website | Section | Subsections | -| ------------------------ | --------------- | ------------------------ | --- | +| ------------------------ | --------------- | ------------------------ | | **Current TUF Website** | Homepage | | | | About | - Overview | | | | - History | @@ -208,16 +204,16 @@ website. | | | - Security audits | | | | - Proposals | | | | - Contribute | -| | | - Chat(CNCF Slack) | +| | | - Chat (CNCF Slack) | | | News | | | | Contact | | -| **Proposed TUF website** | Homepage | | -| | Docs | - Overview: | +| **Proposed TUF Website** | Homepage | | +| | Docs | - Overview | | | | - Project | | | | - Enhancement proposals | | | | - Metadata | | | | - Security audits | -| | | - Getting started | | +| | | - Getting started | | | | - Adoptions | | | | - FAQ | | | Community | - Code of conduct | From 48eba564749286fc949624802c0ed8d1277f5a4e Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 8 Aug 2024 20:01:32 -0400 Subject: [PATCH 95/96] Update .gitignore Signed-off-by: Patrice Chalin --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 16fb088..7807fd3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ # npm assets node_modules/ package-lock.json -.gitpod.yml \ No newline at end of file From 84a8c55d7d382c3b8afc967c0b62f369b8132be5 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 8 Aug 2024 20:02:56 -0400 Subject: [PATCH 96/96] Apply suggestions from code review Signed-off-by: Patrice Chalin --- analyses/0012-TUF/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index 9ea637a..89b1d4a 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,7 +1,5 @@ # TUF Documentation Analysis -[Context: "Status: Draft"] - This section contains analysis of The Update Framework (TUF) project documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group process aimed at assisting cloud-native open-source projects with their