diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md new file mode 100644 index 0000000..89b1d4a --- /dev/null +++ b/analyses/0012-TUF/README.md @@ -0,0 +1,22 @@ +# 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 +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). diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md new file mode 100644 index 0000000..e2b1bea --- /dev/null +++ b/analyses/0012-TUF/analysis.md @@ -0,0 +1,529 @@ +--- +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. + +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 + +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 [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. + +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 and docs: +- Website repo: +- The TUF community repository: + +- TUF specification repository: + +- TUF artwork repository: +- Python reference implementation repository: + + +#### Out of scope + +- TUF Augmentation proposals repository: + +- python-tuf: +- go-tuf: +- tuf-on-ci: + +- RSTUF: + +### 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](./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. + +### 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**. + +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](#project-documentation) + +- [Contributor documentation](#contributor-documentation) + +- [Website and infastructure](#website-and-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 | 2 | +| New user content | 1 | +| Content maintainability | 3 | +| Content creation processes | 1 | +| Inclusive language | 3 | + +Scale: + +1 = Not present + +2 = Needs improvement + +3 = Meets standards + +4 = Meets or exceeds standards + +5 = Exemplary + +### Summary of issues + +- Information is repeated on several pages of the website. For example, the TUF + 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 + 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 + +- Re-organise content to make it easier to follow + +- 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. +- There aren't specific task-based guides for features. + +- There is a FAQ and reporting issues sections for troubleshooting. + +- There is 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 the 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 website repo does not have guides for new users or contributors to get + started + +- 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 + 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. + +- 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. + +#### 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, or easy in the documentation. + +### Project recommendations + +#### Information architecture + +- 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. + +- 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 + +- 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. + +#### Content maintainability & site mechanics + +- Include a search button on the website to make it easier for users to search + and find content. + +- 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 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 + include contribution guidelines to avoid violations. + +- 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. + +#### 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 | 3 | +| Beginner friendly issue backlog | 1 | +| “New contributor” getting started content | 1 | +| Project governance documentation | 3 | + +Scale: + +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. +- 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 + 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 + +#### Communication methods documented + +- 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. + + 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) + +- 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 + +- There's a community section on the website with information on how to join the + community. +- 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. + +#### Project governance documentation + +- The project governance is well documented on the website. There's sufficient + information about it's history including leaders, maintainers and + contributors. However, this information is not visible in the docs repo + README. + +### Contributor recommendations + +#### 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. +- 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. +- Include instructions on how to contribute to a CONTRIBUTING guideline, e.g., + how 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 needs to be included in the docs repo on GitHub. + +## 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 + +- There's no guideline or tutorial to assist users in generating the website + from 5 = Exemplary + +### Summary of Issues + +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 + 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) + +#### Minimal website requirements + +The website docs analysis is in progress. + +#### Usability, accessibility and devices + +- 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 +- 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 the 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 and participating organizations documented in + the _Adoptions_ page. +- 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 + +#### 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 + +### Website recommendations + +#### 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. + +#### 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. + +#### 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 it 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 new file mode 100644 index 0000000..c5fa71d --- /dev/null +++ b/analyses/0012-TUF/implementation.md @@ -0,0 +1,227 @@ +--- +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 [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 +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 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** + under it to avoid repetition + - Structure 'Getting started' according to user roles + - 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 + - Develop quick start and contribution guides for new users + +- **Content maintainability and creation process** + - 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 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 + +## Implementation + +## Reorganize documentation + +### 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: + +- **Home page** +- **Documentation**: Overview of TUF + + - Overview: Metadata,Project,Security + - Getting started: Adopters, contributors, + - History + - Timeline + - Adoptions + - FAQ + +- **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 + components and documentation. + - Code of conduct + +- **Resources**: + - News + - Videos + - Publications and press + +### Consolidate some pages + +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. + +### 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 Adopters and +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 + 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_: 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.) + +- **Contributors**: want to contribute either to the spec or documentation. + - 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. + - Spec contributors + - Docs contributors + +## 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 +- Include links to the GitHub repos associated with the role. + +## Content maintainability and creation process + +### 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, +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. + +### 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. + +### 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 guidelines for new users and contributors + +Develop contributor guides to assist new contributors to get started. + +### Create procedures for developing the website locally + +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 + +Provide information about project meetings and a calendar on both the website +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 + +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 | +| | | | + +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md new file mode 100644 index 0000000..9ffb2b8 --- /dev/null +++ b/analyses/0012-TUF/issues.md @@ -0,0 +1,151 @@ +--- +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 + 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