From 03ca321b1589c1a7cbc416486689f25f4b3f5c51 Mon Sep 17 00:00:00 2001 From: Dindihub Date: Tue, 18 Jun 2024 14:52:31 +0300 Subject: [PATCH 01/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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/95] 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 7fd717204cb7fa3639648a2e826c94a31c5f5e95 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 19:24:16 +0000 Subject: [PATCH 40/95] 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 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 41/95] 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 42/95] 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 43/95] 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 44/95] 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 45/95] 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 46/95] 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 47/95] 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 48/95] 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 49/95] 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 50/95] 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 51/95] 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 52/95] 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 53/95] 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 54/95] 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 55/95] 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 56/95] 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 57/95] 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 58/95] 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 59/95] 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 60/95] 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 61/95] 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 62/95] 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 63/95] 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 6d208a83dac43eb3a1778ef54babf633d6a00d97 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 17 Jul 2024 20:02:18 +0000 Subject: [PATCH 64/95] Edit text in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 0ff6fee..85612e4 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -63,15 +63,14 @@ 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** +- **Home page**: Introduction to TUF project - **Documentation**: Overview of TUF - - Overview: Metadata,Project,Security - - Getting started: Adopters, contributors, - - History - - Timeline - - Adoptions - - FAQ + - TUF project components + - Getting started: Adopters and contributors + - Tutorials + - Implementations + - Best practices - **Community**: You can have two sections. From abc51c356292a328727ea63d376defe3b068271f Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 20 Jul 2024 17:02:38 +0000 Subject: [PATCH 65/95] 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 85612e4..b1f2b60 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 6dd96dcc8309ff934e11836a757a900be845785e Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 20 Jul 2024 19:10:49 +0000 Subject: [PATCH 66/95] create issues documentation foor TUF Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/issues.md | 32 +++----------------------------- 1 file changed, 3 insertions(+), 29 deletions(-) diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md index 898fc71..972f10a 100644 --- a/analyses/0012-TUF/issues.md +++ b/analyses/0012-TUF/issues.md @@ -32,17 +32,9 @@ 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: - -- 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. +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. @@ -51,24 +43,6 @@ 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 68be6df7ad02c5373bae01b9b0ba57da4b016bd1 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 22 Jul 2024 07:46:40 +0000 Subject: [PATCH 67/95] Update users roles subsections in implementation and issue docs Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 11 ----------- analyses/0012-TUF/issues.md | 14 +++++++++++--- 2 files changed, 11 insertions(+), 14 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index b1f2b60..bb39ee5 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -118,17 +118,6 @@ 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 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 0ae353651ff15c4d414471d89afc708ab59da6a5 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 22 Jul 2024 08:19:13 +0000 Subject: [PATCH 68/95] Add README Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index 9ea637a..e0146f5 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,6 +1,4 @@ -# TUF Documentation Analysis - -[Context: "Status: Draft"] +# README This section contains analysis of The Update Framework (TUF) project documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group From edaeeaaef330a89ef89b71affb918f5aef260143 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Thu, 25 Jul 2024 12:37:45 +0000 Subject: [PATCH 69/95] Add analysis table in implemenation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 81 ++++++++++++++--------------- 1 file changed, 38 insertions(+), 43 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index bb39ee5..22542ac 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -170,48 +170,43 @@ notifications about meetings. I like how the ## 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 | -| ------------------------ | --------------- | ------------------------ | --- | -| **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 | -| | | - Security audits | -| | | - Getting started | | -| | | - 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 | +| | | - 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 4f04b002d7d71852fe5fbc699cc4572308e5c634 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Thu, 25 Jul 2024 12:38:42 +0000 Subject: [PATCH 70/95] 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 22542ac..cbbd279 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 3ad621f30e824600b0d9adc0ee447e3bd6395c62 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 18:15:24 +0000 Subject: [PATCH 71/95] 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 cbbd279..6cf22f3 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 58686d2b955e00b83bc037f95f41a873eab7d596 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 72/95] 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 7f91342e3da072c2ef5e0fa7603b1aa708616c7b Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 18:27:21 +0000 Subject: [PATCH 73/95] 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 1900e7a3d7e165831420861f5154195db2c05985 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 19:03:56 +0000 Subject: [PATCH 74/95] Resolve comments Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index e86c914..1fa3669 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -333,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,6 +344,7 @@ Scale: 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 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,11 +383,6 @@ 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 @@ -400,6 +397,8 @@ Scale: - Maintain issues, track,close and stale old issues to reduce backlog. - Include instructions on how to contribute to a CONTRIBUTING guideline, e.g., how interest. +- Include instructions on how to contribute to a CONTRIBUTING guideline, e.g., + how interest. #### New contributor getting started content @@ -440,6 +439,8 @@ Scale: 4 = Meets or exceeds standards +- There's no guideline or tutorial to assist users in generating the website + from 5 = Exemplary - There's no guideline or tutorial to assist users in generating the website from 5 = Exemplary @@ -448,6 +449,9 @@ Scale: navigation option is a menu bar. This makes it difficult to find information. 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 @@ -470,6 +474,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. - There's a recognizable brand for the project, a logo, and a blue-white color +- 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 4a6d4bc6fd3da52b5ad571ebcb2491f4e283094b 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 75/95] 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 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 1fa3669..86b9f70 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -387,8 +387,6 @@ Scale: project or the umbrella repo [theupdateframework](https://github.com/theupdateframework) that lists all TUF 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. From 2a9d02fd0184019b1caf8294a8d52cb74c765e0c Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Mon, 29 Jul 2024 07:46:18 +0000 Subject: [PATCH 76/95] Add suggested improvements to implementation and issue docs Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 95 ++++++++++++++++------------- analyses/0012-TUF/issues.md | 18 ++++++ 2 files changed, 71 insertions(+), 42 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 6cf22f3..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 @@ -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 31817a87e8cca4acf9a489e732fdc6ba589218df Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 16:33:30 +0000 Subject: [PATCH 77/95] 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 82c05e243fb87fa653dbd325cace062ae44d5fc4 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 16:38:07 +0000 Subject: [PATCH 78/95] 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 84e93c5..fdd7575 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -127,6 +127,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 86f61febe67aa0ab3e8a531971dbc37c6c7a97bc Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Thu, 25 Jul 2024 12:38:42 +0000 Subject: [PATCH 79/95] 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 fdd7575..52530d2 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -181,6 +181,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 40e486f8fa6c0ef9f05d8531a5a09aebac1bf40b Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 18:15:24 +0000 Subject: [PATCH 80/95] 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 52530d2..893a57a 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -181,7 +181,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 a87b88a86cc8491bcd5e1ae195401879910457c7 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 26 Jul 2024 19:03:56 +0000 Subject: [PATCH 81/95] Resolve comments Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/analysis.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 86b9f70..ab97d55 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -334,6 +334,7 @@ Scale: 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 - Information about the TUF **slack channel** is available on the website in areas of interest @@ -383,10 +384,17 @@ 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 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. From f07d28356dd319e8125d3c47a1b8c420dafb1972 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 82/95] 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 ab97d55..2d41ad6 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -397,6 +397,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 af6ad446a17123ce47604bd9a6231b1a9b383b89 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 16:56:56 +0000 Subject: [PATCH 83/95] 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 1b63ce60aa2a9e0b6959a1fddb3b270962870388 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Tue, 30 Jul 2024 17:06:03 +0000 Subject: [PATCH 84/95] 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 423236254e65e4e514dffaa2a6c488eeae524bb2 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Wed, 7 Aug 2024 18:40:48 +0000 Subject: [PATCH 85/95] fix table structure in implementation doc Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 893a57a..dfc75f7 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -186,12 +186,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 | @@ -210,16 +206,16 @@ website. | | | - Security audits | | | | - Proposals | | | | - Contribute | -| | | - Chat(CNCF Slack) | +| | | - Chat (CNCF Slack) | | | News | | | | Contact | | -| **Proposed TUF website** | Homepage | | +| **Proposed TUF Website** | Homepage | | | | Docs | - Overview | | | | - Project | | | | - Enhancement proposals | | | | - Metadata | -| | | - Getting started | | | | | - Security audits | +| | | - Getting started | | | | - Adoptions | | | | - FAQ | | | Community | - Code of conduct | From 25d61702a57031675fe3bd3e94a82753f484dd74 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Fri, 9 Aug 2024 09:09:17 +0000 Subject: [PATCH 86/95] Add specs to new IA Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index dfc75f7..1161ddb 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -182,7 +182,7 @@ notifications about meetings. I like how the ## Proposed Information Architecture for the TUF Website -The table below outlines the current information architecture(IA) of the +The table below outlines the current information architecture (IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. @@ -218,6 +218,8 @@ website. | | | - Getting started | | | | - Adoptions | | | | - FAQ | +| | Specs | -Specification (latest) | +| | | - Specification index | | | Community | - Code of conduct | | | | - Learn and connect | | | | - Develop and contribute | From 3ac3d6caa7f5a5855a48da6315271e8c5aeaec57 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 10 Aug 2024 08:36:07 +0000 Subject: [PATCH 87/95] solve merge conflicts Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index 9ea637a..8970a71 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,6 +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 From 2bd18abce776c898f7ea01b43ad392063c3d9f9c Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 10 Aug 2024 08:50:39 +0000 Subject: [PATCH 88/95] resolve merge conflicts Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/README.md | 1 - analyses/0012-TUF/implementation.md | 4 ++-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md index 8970a71..89b1d4a 100644 --- a/analyses/0012-TUF/README.md +++ b/analyses/0012-TUF/README.md @@ -1,6 +1,5 @@ # TUF Documentation Analysis - 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 diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 1161ddb..b22de13 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -218,8 +218,8 @@ website. | | | - Getting started | | | | - Adoptions | | | | - FAQ | -| | Specs | -Specification (latest) | -| | | - Specification index | +| | Specification | -Specification (latest) | +| | | - Specification index | | | Community | - Code of conduct | | | | - Learn and connect | | | | - Develop and contribute | From 32b9dc5cb035a2a7aeae845e2aecbdd3d6827d23 Mon Sep 17 00:00:00 2001 From: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> Date: Tue, 2 Jul 2024 10:05:49 +0900 Subject: [PATCH 89/95] Initialize the Japanese Localization Guidelines (#259) * feat: initialize Japanese l10n guide Signed-off-by: Junya Okabe * update: add review section Signed-off-by: Junya Okabe * fix: anchor link Signed-off-by: Junya Okabe * Update: l10n reviewer Signed-off-by: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> Signed-off-by: Junya Okabe * fix: linter errors Signed-off-by: Junya Okabe * feat: add ## Localization READMEs Signed-off-by: Junya Okabe * fix: link checker error Signed-off-by: Junya Okabe * update: .prettierignore Signed-off-by: Junya Okabe * Update docs/localization/README.md Co-authored-by: Patrice Chalin Signed-off-by: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> * Update .prettierignore Co-authored-by: Patrice Chalin Signed-off-by: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> * fix: L6 Signed-off-by: Junya Okabe --------- Signed-off-by: Junya Okabe Signed-off-by: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> Co-authored-by: Patrice Chalin --- .prettierignore | 2 +- docs/localization/README.md | 4 ++ docs/localization/ja/README.md | 73 ++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 docs/localization/ja/README.md diff --git a/.prettierignore b/.prettierignore index ec634b6..f238ae8 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1 +1 @@ -# Nothing to ignore at the moment. +/docs/localization/ja diff --git a/docs/localization/README.md b/docs/localization/README.md index aae60c1..9ca8025 100644 --- a/docs/localization/README.md +++ b/docs/localization/README.md @@ -11,3 +11,7 @@ Every guide here must meet the following requirements: - Meets the requirements of the original open-source license. Guides here must not violate copyright or licensing requirements. + +## Localizations + +- [Japanese](ja/README.md) diff --git a/docs/localization/ja/README.md b/docs/localization/ja/README.md new file mode 100644 index 0000000..265ff8b --- /dev/null +++ b/docs/localization/ja/README.md @@ -0,0 +1,73 @@ +# CNCF日本語ローカライゼーション向けガイドライン + +このドキュメントでは、CNCFのプロジェクトをローカライズする際に参考になる一般的なガイドラインを提供します。 + +> [!IMPORTANT] +> 各プロジェクトに対してこのガイドラインをどの程度適用するかは、各プロジェクトのローカライゼーションリードが決定します。疑問点がある場合は、各プロジェクトの日本語ローカライゼーションリードやレビュアーと相談してください。 + +## 目次 + +- [スタイルガイド](#スタイルガイド) +- [固有の用語](#固有の用語) + - [例](#例) +- [レビュー](#レビュー) +- [プロジェクト](#プロジェクト) +- [コミュニケーション](#コミュニケーション) + +## スタイルガイド + +Kubernetesの[日本語ローカライゼーション向けのスタイルガイド](https://kubernetes.io/ja/docs/contribute/localization/#style-guide)に準拠してください。 + +## 固有の用語 + +CNCFのプロジェクト特有の用語については、原則として英語のまま表記してください。ただしこれらの用語や概念を説明をするページなどで日本語の訳語が必要な場合は、以下の表を参考にしてください。 + +| 英語 | 日本語 | +| --- | --- | +| Charter | チャーター | +| Governing Board | 運営委員会 | +| SIG (Special Interest Group) | Special Interest Group | +| TAB (Technical Advisory Board) | 技術諮問評議会 | +| TAG (Technical Advisory Group) | 技術諮問グループ | +| TOC (Technical Oversight Committee) | 技術監督委員会 | +| WG (Working Group) | ワーキンググループ | + +また次の表に示す用語はCNCF特有ではありませんが、表記を統一するため、原則として以下の表を参考にしてください。 + +| 英語 | 日本語 | +| --- | --- | +| Committee | 委員会 | +| White Paper | ホワイトペーパー | + +### 例 + +| 推奨 | 非推奨 | +| --- | --- | +| Platform WG | プラットフォームWG | +| Platform WG | プラットフォームワーキンググループ | +| SIG Docs | SIGドキュメント | +| TAG Runtime | TAGランタイム | + +## レビュー + +ローカライゼーションのPRを作成した際は、ローカライゼーションレビュアーにレビューを依頼してください。各リポジトリのレビュアーは、[プロジェクト](#プロジェクト)の表を参考にしてください。 +2人以上のローカライゼーションレビュアーからの承認を得ることを推奨します。 + +ローカライゼーションレビュアーからの承認を得た後、各リポジトリのメンテナーにPRのマージを依頼してください。 + +## プロジェクト + +すでにローカライゼーションが進められているプロジェクトの一覧です。ローカライゼーションPRを作成する際には、以下の表を参考にして、適宜ローカライゼーションリードやレビュアーに通知してください。 + +| プロジェクト | ローカライゼーションリード | ローカライゼーションレビュアー | +| --- | --- | --- | +| [CNCF Glossary](https://github.com/cncf/glossary) | [@naonishijima](https://github.com/naonishijima) | [@naonishijima](https://github.com/naonishijima), [@kaitoii11](https://github.com/kaitoii11), [@Okabe-Junya](https://github.com/Okabe-Junya) | +| [CNCF TAG App Delivery](https://github.com/cncf/tag-app-delivery) | [@hhiroshell](https://github.com/hhiroshell) | [@hhiroshell](https://github.com/hhiroshell), [@kaitoii11](https://github.com/kaitoii11), [@naonishijima](https://github.com/naonishijima) | +| [CNCF TAG Environmental Sustainability](https://github.com/cncf/tag-env-sustainability) | [@naonishijima](https://github.com/naonishijima) | [@naonishijima](https://github.com/naonishijima), [@kaitoii11](https://github.com/kaitoii11), [@Okabe-Junya](https://github.com/Okabe-Junya) | +| [CNCF TAG Runtime](https://github.com/cncf/tag-runtime) | [@kaitoii11](https://github.com/kaitoii11) | [@kaitoii11](https://github.com/kaitoii11), [@kenta-iijima](https://github.com/kenta-iijima), [@Okabe-Junya](https://github.com/Okabe-Junya) | + +## コミュニケーション + +CNCFのプロジェクトのローカライゼーションに関するコミュニケーションは、主に、[CNCFのSlack](https://cloud-native.slack.com)の[`#glossary-localization-japanese`](https://cloud-native.slack.com/archives/C057F81GFUG)チャンネルで行われています。ローカライゼーションに関する質問や提案がある場合は、こちらのチャンネルで議論してください。 + +CNCFのSlackに参加していない場合は、[Community Inviterのサイト](https://communityinviter.com/apps/cloud-native/cncf)から参加できます。 From e47cb35b117cabf5cbffc95f4d07c104af7fa2a3 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 29 Jul 2024 17:52:20 -0400 Subject: [PATCH 90/95] Fix broken link from Keda analysis (#268) Signed-off-by: Patrice Chalin --- analyses/0011-keda/keda-implementation.md | 2 +- analyses/0011-keda/keda-issues.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index 7508886..a57b89a 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -137,7 +137,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... - - [FAQ](https://keda.sh/docs/2.13/faq/) + - [FAQ](https://keda.sh/docs/latest/faq/) - Glossary - [Scalers](https://keda.sh/docs/2.13/scalers/) - [ActiveMQ](https://keda.sh/docs/2.13/scalers/activemq/) diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index 2d3bb63..e8d1f50 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -180,7 +180,7 @@ or provide a starting point. - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... - - [FAQ](https://keda.sh/docs/2.13/faq/) + - [FAQ](https://keda.sh/docs/latest/faq/) - Glossary # Separate reference and task information From f6c3e97c4e1ef36fab77884057783740b1cebef7 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Tue, 30 Jul 2024 11:58:51 -0700 Subject: [PATCH 91/95] Criteria: sandbox update/clarification (#266) * Update README.md Corrected with new directory structure. Reorganized description. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Updated sandbox website assessment requirement. Miscellaneous small corrections. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update README.md Fix formatting errors, primarily line legth/LINT. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Fix MD linter and line-length errors. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update README.md Trailing spaces? Really? Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update keda-implementation.md Fixed faq link Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update keda-issues.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * fixing formatting issues brought up by prettier Signed-off-by: Nate W * Update docs/analysis/criteria.md Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Nate W * Update assistance.md Added a note to address program differences for projects at the Sandbox maturity level. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update assistance.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --------- Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Nate W Co-authored-by: Nate W --- README.md | 62 +++++++++++------------ analyses/0011-keda/keda-implementation.md | 2 +- analyses/0011-keda/keda-issues.md | 2 +- docs/analysis/criteria.md | 50 ++++++++++-------- docs/assistance.md | 13 +++-- 5 files changed, 72 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index b19c2bf..be0b70e 100644 --- a/README.md +++ b/README.md @@ -3,35 +3,24 @@ This repository holds resources provided by the CNCF Technical Documentation team. The repo contains the following directories: -- `analysis` contains instructions, templates, and criteria for requesting and - performing an analysis of an OSS project's website and technical - documentation. Completed analyses are stored here as well. -- `resources` contains information that OSS teams can use to set up a - documentation project as suggested by the TechDocs team. +- `docs` contains collected resources for building websites and developing + documentation, including recommended tools and practices, how-tos, and + evaluation checklists. Included are specific guidelines for: + - Setting up and maintaining a documentation website. + - Writing technical documentation for a project. + - Getting assistance from the CNCF TechDocs community. + - Analyzing project documentation, for use by CNCF TechDocs staff (in + `docs/analysis`). +- `analyses` (not to be confused with `docs/analysis`) contains all the + completed documentation analyses. -## CNCF TechDocs team - -The full-time staff of the CNCF Tech Docs team is: - - - -| GitHub ID | Role | -| -------------------------------------------------- | ------------------------------------- | -| [@chalin](https://github.com/chalin) | Senior technical writer | -| [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer | -| [@thisisobate](https://github.com/thisisobate) | Developer advocate | - - - - -Various consultants and volunteers also contribute to CNCF Tech Docs projects. +## TechDocs Q&A -## Office hours +The CNCF tech docs team holds a Zoom call to answer questions and discuss +anything to do with documentation. Calls are held on the [fourth Wednesday of +every month at 8am Pacific time][date-time]. -The CNCF tech docs team holds office hours on the [fourth Wednesday of every -month at 8am Pacific time][date-time]. - -Office hours started on 30 September 2020. +TechDocs Q&A (formerly called _Office Hours_) started on 30 September 2020. ### Meeting link @@ -44,15 +33,26 @@ We store ongoing meeting notes in a ## Assistance program for technical documentation -The TechDocs team can assist CNCF projects analyze and improve their +The TechDocs team can help CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance program](docs/assistance.md). -### Resources +## CNCF TechDocs team + +The full-time staff of the CNCF Tech Docs team is: + + + +| GitHub ID | Role | +| -------------------------------------------------- | ------------------------------------- | +| [@chalin](https://github.com/chalin) | Senior technical writer | +| [@nate-double-u](https://github.com/nate-double-u) | Developer advocate & technical writer | +| [@thisisobate](https://github.com/thisisobate) | Developer advocate | + + + -The `docs/` directory contains collected resources for building websites and -developing documentation, including recommended tools and practices, how-tos, -and evaluation checklists. +Various consultants and volunteers also contribute to CNCF Tech Docs projects. [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index a57b89a..a759b48 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -137,7 +137,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... - - [FAQ](https://keda.sh/docs/latest/faq/) + - [FAQ](https://keda.sh/docs/2.13/reference/faq/) - Glossary - [Scalers](https://keda.sh/docs/2.13/scalers/) - [ActiveMQ](https://keda.sh/docs/2.13/scalers/activemq/) diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index e8d1f50..c46e690 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -180,7 +180,7 @@ or provide a starting point. - [Events](https://keda.sh/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... - - [FAQ](https://keda.sh/docs/latest/faq/) + - [FAQ](https://keda.sh/docs/2.13/reference/faq/) - Glossary # Separate reference and task information diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index c0c9e61..e6719fb 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -21,7 +21,7 @@ documentation. We evaluate on the following: - If the product exposes an API, is there a complete reference? - Is content up to date and accurate? -Examples: +Example: - @@ -39,7 +39,10 @@ specifically for them. We evaluate on the following: top of your information architecture? - Is there easily copy-pastable sample code or other example content? -Examples: + + + +Example: - @@ -55,7 +58,7 @@ We evaluate on the following: directory structure? Is a localization framework present? - Do you have a clearly documented method for versioning your content? -Examples: +Example: - @@ -105,7 +108,7 @@ We evaluate on the following: join those meetings? - Are mailing lists documented? -Examples: +Example: - @@ -119,7 +122,7 @@ We evaluate on the following: - Are issues well-documented (i.e., more than just a title)? - Are issues maintained for staleness? -Examples: +Example: - (all of open tracing’s backlogs are well maintained!) @@ -136,7 +139,7 @@ We evaluate on the following: - Is there a document specifically for new contributors/your first contribution? - Do new users know where to get help? -Examples: +Example: - @@ -148,9 +151,9 @@ We evaluate on the following: - Is project governance clearly documented? -Examples: +Example: -- Any graduated CNCF project +- ## Website @@ -181,16 +184,20 @@ maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. - **Sandbox** - - [Website guidelines](../website-guidelines-checklist.md): majority of the + - [Website guidelines](../website-guidelines-checklist.md): a majority of the guidelines are satisfied - - [Docs assessment][]: consider [submitting a request][service desk] for an assessment - as early as possible to avoid documentation and website rework. - **Project documentation** may or may not be present -- it is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website - - _Example_: website with a single homepage, without any documentation or, as - was mentioned above, linking out to an external (preexisting) source for - docs + - _Example_: website with a single homepage, without any documentation or, + as was mentioned above, linking out to an external (preexisting) source + for docs + - _However_: consider reading the recommended practices in this repository + and implementing as many of the best practices as you can. This groundwork + will pay big dividends later when you need to upgrade your practices and + update your documentation as an incubating project. Assistance is + available from CNCF TechDocs anytime, including answers to individual + questions or a documentation workshop. - **Incubating** - [Website guidelines][]: all guidelines are satisfied. - [Docs assessment][]: request an (re-)assessment through the CNCF [service @@ -207,7 +214,7 @@ requirements for sandbox projects. - The website repo is in an [archived state][] - The archived status of the project must be obvious to those visiting the website, such as through the use of a prominent banner. - - If a successor project exists, link to it's website and/or migration + - If a successor project exists, link to its website and/or migration documentation. [archived state]: @@ -254,9 +261,9 @@ We evaluate on the following: - Is there an easily recognizable brand for the project (logo + color scheme) clearly identifiable? - Is the brand used across the website consistently? -- Is the website’s typography clean and well-suited for reading? +- Is the website’s typography clean and legible? -Examples: +Example: - @@ -282,9 +289,10 @@ Examples: ### SEO, Analytics and site-local search -SEO helps users find your project and it's documentation, and analytics helps -you monitor site traffic and diagnose issues like page 404s. Intra-site search, -while optional, can offer your readers a site-focused search results. +SEO helps users find your project and its documentation, and analytics helps you +monitor site traffic and diagnose issues like page 404s. Intra-site search, +while optional, offers your readers site-focused search results and is strongly +recommended. We evaluate on the following: @@ -313,7 +321,7 @@ We evaluate on the following: - Are site build times reasonable? - Do site maintainers have adequate permissions? -Examples: +Example: - diff --git a/docs/assistance.md b/docs/assistance.md index a322e87..5362657 100644 --- a/docs/assistance.md +++ b/docs/assistance.md @@ -1,9 +1,9 @@ # Assistance program for technical documentation This document outlines the Cloud Native Computing Foundation (CNCF) Technical -Documentation Assistance Program (the Program), a service offered by CNCF Tech -Docs for evaluating and improving an OSS project's technical documentation. The -process is designed to: +Documentation Assistance Program (the Program), a service offered by CNCF +TechDocs for evaluating and improving an OSS project's technical documentation. +The process is designed to: 1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](analysis/criteria.md). Often, projects @@ -18,6 +18,13 @@ process is designed to: 1. Leave the project team with an improved understanding and skill base for improving and maintaining the project documentation. +**Note**: The Program focuses on established projects at the _incubating_ and +_graduated_ maturity levels. The Program offers help for _sandbox_ projects as +well, but with less emphasis on analyzing existing documentation and more on +establishing good practices and starting a minimally viable documentation set. +For more information contact the +[CNCF TechDocs team](https://servicedesk.cncf.io/). + ## Phase 0: Training Some level of familiarity with the technical documentation process is required From 552c917247629373ad8944f356e1b0bb9b7673a5 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Wed, 7 Aug 2024 16:06:12 -0700 Subject: [PATCH 92/95] Sandbox process (#269) * Added sandbox doc primer sandbox-doc-primer.md defines terms and outlines a process for getting started with project documentation in CNCF. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * fixing formatting Signed-off-by: Nate W * Update sandbox-doc-primer.md - Added release notes as an example of reference doc - Added links to more resources - Minor edits Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update sandbox-doc-primer.md Fixed format issue? Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update sandbox-doc-primer.md Added info about CNCF hosting project websites. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * fixing formatting Signed-off-by: Nate W --------- Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Nate W Co-authored-by: Nate W --- docs/sandbox-doc-primer.md | 225 +++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 docs/sandbox-doc-primer.md diff --git a/docs/sandbox-doc-primer.md b/docs/sandbox-doc-primer.md new file mode 100644 index 0000000..43c6a63 --- /dev/null +++ b/docs/sandbox-doc-primer.md @@ -0,0 +1,225 @@ +# CNCF sandbox project documentation primer + +This document is a quick primer for CNCF project maintainers and contributors +who need to document their projects but don't know where to start. It provides a +framework for thinking about user documentation that will enable the project +contributors to write effective documentation from the very beginning and to get +the most out of documentation efforts as the project matures. + +## What is "good" documentation? + +Documentation quality is ultimately measured by how _effective_ it is. + +The purpose of documentation is to help the user of a product achieve their +objectives. The scope of these objectives ranges from individual tasks (use a +command correctly, connect to a database) to large-scale goals (write a software +product or module; configure a server farm). Objectives also vary by +[user role](#product-users) (new developer; software architect; IT +administrator). + +Documentation effectiveness, therefore, is defined by _how well it enables a +user to succeed in achieving their objectives_, within every range of scope and +for all users. + +### An information model for user documentation + +This discussion uses the following +[model](https://www.lios.ca/en/blogue/concept-task-reference/) to categorize +types of technical documentation. + +A documentation topic is one of these three types, depending on its purpose: + +- _Conceptual_ information describes one or more aspects of the project or its + products: its structure, purpose, motivation, architecture – almost anything. + Examples include: + - architectural overviews + - product histories + - technical white papers + - design discussions +- _Task-based_ information describes how to do something. Examples include: + - procedure documentation, from individual task instructions to full + instruction manuals + - code "recipes" for creating particular software components + - specialized instructions such as troubleshooting guides + - learning materials such as tutorials +- _Reference_ information is the "lookup" material specific to a product. + Examples include: + - API specifications + - command references + - knowledge bases + - user interface references + - error code lookups + - glossaries + - release notes + +### Descriptive vs. instructional documentation + +No type of information is "better" than any other. All three types are necessary +to good technical documentation and should be present in the docs for any +software product. + +That said, however, documentation writers involved with product development tend +to write _descriptive_ documentation: they emphasize conceptual and reference +information at the expense of task-based information. + +It's important, especially when developing a product, to describe what the +product is designed to do. But in general, this does not make good user +documentation. Descriptive documentation forces the user to search the +documentation for a combination of features that will accomplish their goal, +rather than being able to pursue that goal directly. + +Good software documentation is primarily _instructional_. The core of the +documentation set aims to help users efficiently accomplish their goals. A +traditional documentation set might contain a _getting started guide_ to help +the user set up their workspace; _tutorials_ to teach skills and techniques; a +_user guide_ (or _developer guide_) to explain and illustrate tools and +workflows; and a _reference guide_ (often built into an IDE) to look up APIs, +commands, or other toolkit components. + +Of course it's important that the documentation be feature-complete – that every +capability of the product be documented. But it's equally important that every +task that a user would reasonably want to perform be documented. A good cookbook +doesn't just list ingredients, it tells you how to use them. + +## A process for developing user documentation + +So if starting with design documentation and expanding on the product's +functionality isn't the best way to write user documentation, what is? + +Answer: To develop effective documentation it is necessary to describe the +product's users and their objectives. This might seem like unnecessary extra +work, but it will pay off very quickly in documentation quality. + +The rest of this document is a very brief description of a system for writing +effective documentation for all of a product's users. + +### Product users + +First, define your product's _user roles_. A user role (also called a +_persona_), is a type of user with a particular set of tasks they need to +perform. + +As an example, consider a hypothetical product that consists of a REST API +frontend to a server-based relational database. The user roles are: + +- _Developer_: Uses the REST API to list data records and perform CRUD + operations on the database. +- _Administrator_: Sets up and maintains the product on one or more servers, + including a production server. + +For any OSS project, there are also these roles: + +- _Contributor_: A member of the project community who contributes code or other + labor to the project itself. +- _Evaluator_: Someone who is considering using the product and needs to find + out more about it. + +One person can have multiple roles. For example, a contributor is often also a +user (developer or admin, in this case). + +### Write goals + +Next, determine the goals of each user role that are served by the product. For +the developer in the database example, a goal is probably to integrate the +database into an end-user application. + +For the admin, a goal is to set up, say, a production and a test server and to +populate them with identical data. + +### Develop tasks + +Analyze larger goals down to smaller ones. Ultimately, you want to get to the +most basic unit of task-based documentation: discrete step-by-step tasks. + +#### Write for new users + +Pay special attention to the goals of new users. + +For example, new-user goals for developers always include: + +- Installing dependencies and software +- Configuring a development environment +- Running a "hello world" example or a similar simple task to verify the product + +When writing for new users (or indeed, any user who isn't part of the +contributor community), try not to assume that the user knows anything about the +product. This is especially true when writing task documentation. + +In the database example, say that configuring the server consists of copying the +config file template to the config directory, setting permissions on the file, +and editing the file to include the server IPs and some other parameters. Time +and again we've seen configuration documentation that consists only of which +config parameters to set. An effective configuration task, though, would walk +through these steps: + +1. Copy the template from folder X to folder Y. +1. Name the file Z. +1. Set permissions on the file to ABC. +1. Edit the file to set parameters Q, R, S and T. (And include a link to the + config reference\!) + +Don't worry about giving too much information. Novice users need it, and expert +users will ignore it. + +### Support the task documentation + +Finally, support the task documentation with conceptual and reference +documentation. The developer, for example, will need a complete reference for +the REST API. The admin will need a complete description of every server +configuration option. Both will need a reference for the CLI, if there is one. + +Conceptual information should always include a technical overview. This includes +the product's purpose, architecture, and design rationales. This helps +prospective users decide whether it's a solution for their problem, and helps +advanced users reason about how to use or even extend its advanced features. + +## Nuts and bolts: deliverables and infrastructure + +### Required documentation + +A minimal documentation set varies by product, but some documents are (almost) +always required to make the product usable: + +- A technical overview +- A getting started guide +- Reference manual(s) + +[Here's more](https://expertsupport.com/library/quick-and-easy-document-specifications/) +on how to determine which docs you really need. + +### Where to put it + +At the sandbox stage, making the documentation available in some form is more +important than hosting it in any particular place. That said, CNCF TechDocs has +a [number of resources](https://github.com/cncf/techdocs/tree/main/docs) for +creating web-based documentation. + +CNCF TechDocs can purchase, set up, and maintain your website's domain at no +cost to your project. Contact CNCF TechDocs through the +[CNCF TechDocs Service Desk](https://servicedesk.cncf.io) to request website +hosting. + +Even if you don't use the CNCF recommended tools, it's worth reading the +recommendations to preview the sorts of issues you'll encounter as the +documentation matures. These issues parallel those facing the code +infrastructure, and include things like scaling, hosting, versioning, indexing, +SEO, and finding contributing writers. + +### What’s next + +For a thorough preparation in working with technical documentation, the +following resources are available: + +[Open Source Documentation Essentials](https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/) +and +[Creating Effective Documentation for Developers](https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/) +are free courses offered by CNCF and the Linux Foundation. + +[Google for Developers](https://developers.google.com) offers +[free technical writing courses](https://developers.google.com/tech-writing). + +[Docs for Developers](https://docsfordevelopers.com/) is a guide to writing +user-oriented documentation for software engineers. + +For advice and next steps with documentation for a CNCF sandbox project, contact +the [CNCF TechDocs team](https://github.com/cncf/techdocs/blob/main/README.md). From 0ed4ff914e3327daf09b3a154f3842a6b2536d33 Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 9 Aug 2024 03:06:01 +0300 Subject: [PATCH 93/95] Docs: TUF docs Analysis and Improvement (#261) --- analyses/0012-TUF/analysis.md | 10 ---------- analyses/0012-TUF/implementation.md | 14 +++++--------- 2 files changed, 5 insertions(+), 19 deletions(-) diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md index 2d41ad6..e2b1bea 100644 --- a/analyses/0012-TUF/analysis.md +++ b/analyses/0012-TUF/analysis.md @@ -334,7 +334,6 @@ Scale: 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 - Information about the TUF **slack channel** is available on the website in areas of interest @@ -345,7 +344,6 @@ Scale: 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 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) @@ -404,8 +402,6 @@ Scale: - Maintain issues, track,close and stale old issues to reduce backlog. - Include instructions on how to contribute to a CONTRIBUTING guideline, e.g., how interest. -- Include instructions on how to contribute to a CONTRIBUTING guideline, e.g., - how interest. #### New contributor getting started content @@ -446,8 +442,6 @@ Scale: 4 = Meets or exceeds standards -- There's no guideline or tutorial to assist users in generating the website - from 5 = Exemplary - There's no guideline or tutorial to assist users in generating the website from 5 = Exemplary @@ -456,9 +450,6 @@ Scale: navigation option is a menu bar. This makes it difficult to find information. 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 @@ -481,7 +472,6 @@ 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. - There's a recognizable brand for the project, a logo, and a blue-white color -- 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 diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index b22de13..c5fa71d 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. @@ -182,7 +180,7 @@ notifications about meetings. I like how the ## Proposed Information Architecture for the TUF Website -The table below outlines the current information architecture (IA) of the +The table below outlines the current information architecture(IA) of the [TUF website](https://theupdateframework.io/) and the proposed IA for the new website. @@ -218,8 +216,6 @@ website. | | | - Getting started | | | | - Adoptions | | | | - FAQ | -| | Specification | -Specification (latest) | -| | | - Specification index | | | Community | - Code of conduct | | | | - Learn and connect | | | | - Develop and contribute | From 4a70b0002b5d51d4ccdc4c0e728fbf1078bfc5c3 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 10 Aug 2024 09:03:00 +0000 Subject: [PATCH 94/95] fix merge conflicts Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index c5fa71d..8cddf5f 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -216,6 +216,8 @@ website. | | | - Getting started | | | | - Adoptions | | | | - FAQ | +| | Specification | - Specification (latest) | +| | | - Specification index | | | Community | - Code of conduct | | | | - Learn and connect | | | | - Develop and contribute | From 801729d480447616db7d6cd6cbd407981be4c755 Mon Sep 17 00:00:00 2001 From: Dindihub Dindi Date: Sat, 10 Aug 2024 09:04:33 +0000 Subject: [PATCH 95/95] fix merge conflicts Signed-off-by: Dindihub Dindi --- analyses/0012-TUF/implementation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index 8cddf5f..7f18de4 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -216,8 +216,8 @@ website. | | | - Getting started | | | | - Adoptions | | | | - FAQ | -| | Specification | - Specification (latest) | -| | | - Specification index | +| | Specification | - Specification (latest) | +| | | - Specification index | | | Community | - Code of conduct | | | | - Learn and connect | | | | - Develop and contribute |