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