From cafde379fea2bdd8ded0647bbad9f641b5842795 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 30 Jun 2024 19:26:39 -0400 Subject: [PATCH] Ran fix:format; fix markdown, copyedits --- 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