diff --git a/.github/settings.yml b/.github/settings.yml index d7b6b3c..5e287df 100644 --- a/.github/settings.yml +++ b/.github/settings.yml @@ -65,31 +65,31 @@ labels: - name: p3-low color: FEF2C0 - name: e0-minutes - description: "Effort: < 60 min" + description: 'Effort: < 60 min' color: e6ccb3 - name: e1-hours - description: "Effort: < 8 hrs" + description: 'Effort: < 8 hrs' color: d9b38c - name: e2-days - description: "Effort: < 5 days" + description: 'Effort: < 5 days' color: cc9966 - name: e3-weeks - description: "Effort: < 4 weeks" + description: 'Effort: < 4 weeks' color: bf8040 - name: e4-months - description: "Effort: 1+ months" + description: 'Effort: 1+ months' color: 996633 - name: Docs Assessment - description: "CNCF TechDocs Assessments" + description: 'CNCF TechDocs Assessments' color: c2e0c6 - name: Website Update - description: "CNCF Help request for project website updates" + description: 'CNCF Help request for project website updates' color: BFAFE3 - name: suggested doc - description: "New doc suggestions for the docs/ section" + description: 'New doc suggestions for the docs/ section' color: 89E295 - name: admin - description: "TechDocs administration activities" + description: 'TechDocs administration activities' color: 000000 # Default new repo labels - name: bug @@ -122,4 +122,3 @@ labels: - name: CNCF Service Desk description: This issue has a related CNCF Service Desk ticket color: 0CD9EF - diff --git a/.prettierignore b/.prettierignore index 2709d58..ec634b6 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,8 +1 @@ -.github - -# temporary - -# Until https://github.com/cncf/techdocs/pull/229 is merged -analyses -docs -/README.md +# Nothing to ignore at the moment. diff --git a/README.md b/README.md index eb3ed1d..2b9a731 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,20 @@ # CNCF TechDocs -This repository holds resources provided by the CNCF Technical Documentation team. The repo contains the following directories: +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. +- `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. ## 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 | @@ -21,22 +25,29 @@ Various consultants and volunteers also contribute to CNCF Tech Docs projects. ## Office hours -The CNCF tech docs team holds office hours on the [fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours). +The CNCF tech docs team holds office hours on the +[fourth Wednesday of every month at 8am Pacific time](https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours). Office hours started on 30 September 2020. ### Meeting link -Zoom link: https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e +Zoom link: +https://zoom-lfx.platform.linuxfoundation.org/meeting/95471930872?password=db1aa715-a60b-444c-8b14-71d44161a42e ### Meeting notes -We store ongoing meeting notes in a [Google doc](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/). +We store ongoing meeting notes in a +[Google doc](https://docs.google.com/document/d/1roexHTLCrErYjNT2NEoRsVnn_YNbQzZ1gyXNK8hXR4Q/). ## Assistance program for technical documentation -The TechDocs team can assist CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance program](docs/assistance.md). +The TechDocs team can assist CNCF projects analyze and improve their +documentation. For details, see the TechDocs +[assistance program](docs/assistance.md). ### Resources -The `docs/` directory contains collected resources for building websites and developing documentation, including recommended tools and practices, how-tos, and evaluation checklists. \ No newline at end of file +The `docs/` directory contains collected resources for building websites and +developing documentation, including recommended tools and practices, how-tos, +and evaluation checklists. diff --git a/analyses/0001-contour.md b/analyses/0001-contour.md index a76f8d6..5cb981f 100644 --- a/analyses/0001-contour.md +++ b/analyses/0001-contour.md @@ -5,189 +5,295 @@ Prepared by: Celeste Horgan ([@celestehorgan](https://github.com/celestehorgan)) Date: March 2021 -This is an assessment of your project documentation and website (if present), prepared for you and your project by the CNCF techdocs team. +This is an assessment of your project documentation and website (if present), +prepared for you and your project by the CNCF techdocs team. This document aims to: - Measure existing documentation quality against the CNCF’s standards - Recommend specific and general improvements -- Provide examples of great documentation as reference -- Identify key areas which will net the largest improvement if addressed +- Provide examples of great documentation as reference +- Identify key areas which will net the largest improvement if addressed ## How this document works -The assessment is divided into three sections: +The assessment is divided into three sections: -- **Project documentation:** for end users of the project; aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project +- **Project documentation:** for end users of the project; aimed at people who + intend to use it +- **Contributor documentation:** for new and existing contributors to the + project - **Website:** branding, website structure, and maintainability -Within each section you receive a rating on different criteria. The full definition of each criteria is defined in [the criteria](criteria.md). We recommend reading each criterion’s definition. +Within each section you receive a rating on different criteria. The full +definition of each criteria is defined in [the criteria](criteria.md). We +recommend reading each criterion’s definition. -## Project documentation +## Project documentation - -| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | -| --- | --- | --- | --- | --- | --- | -| Information architecture | | | | ✅ | | -| New user content | | | | ✅ | | -| Content maintainability | | | ✅ | | | -| Content creation processes | | ✅ | | | | +| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | +| -------------------------- | ------------------------------------------------- | --- | -------------------------------- | --- | ----------------------------------------------------------- | +| Information architecture | | | | ✅ | | +| New user content | | | | ✅ | | +| Content maintainability | | | ✅ | | | +| Content creation processes | | ✅ | | | | ### Comments -- **Information Architecture**: - - Documentation is feature complete! - - A clear "About" or "What is Contour?" page is missing. It partially exists on (Architecture)[https://projectcontour.io/docs/v1.13.1/architecture/] and (Philosophy)[https://projectcontour.io/resources/philosophy/], but it's hard to navigate for a new user. - - Task and concept documentation for individual features (configurations and deployment options) are both feature complete. - - Because documentation for this project involves long examples, it might be useful to have a reference table of different config options and the expected data types for each value. - - There's lots of great examples for different configuration and deployment options, but there's no clear "happy path" through the content. I'm a new user and I've decided I want to use Contour. What's considered a "basic" Contour setup and how can I get there? - - Your API reference looks great, but some internal navigation on the reference page (hashlinks and a submenu) would be helpful. - - Judging purely by the git commit history, content is up to date. To further you as a team, it might be useful to figure out a quarterly/yearly "stale content" checking cycle. - - The only place troubleshooting is mentioned is (in the getting started guide)[https://projectcontour.io/getting-started/#troubleshooting]. It's worth emphasizing this elsewhere (i.e. a page in the docs or a mention on the docs landing page). This will help as the project grows and people start using GitHub as a support portal :) +- **Information Architecture**: + + - Documentation is feature complete! + - A clear "About" or "What is Contour?" page is missing. It partially exists + on (Architecture)[https://projectcontour.io/docs/v1.13.1/architecture/] and + (Philosophy)[https://projectcontour.io/resources/philosophy/], but it's hard + to navigate for a new user. + - Task and concept documentation for individual features (configurations and + deployment options) are both feature complete. + - Because documentation for this project involves long examples, it might be + useful to have a reference table of different config options and the + expected data types for each value. + - There's lots of great examples for different configuration and deployment + options, but there's no clear "happy path" through the content. I'm a new + user and I've decided I want to use Contour. What's considered a "basic" + Contour setup and how can I get there? + - Your API reference looks great, but some internal navigation on the + reference page (hashlinks and a submenu) would be helpful. + - Judging purely by the git commit history, content is up to date. To further + you as a team, it might be useful to figure out a quarterly/yearly "stale + content" checking cycle. + - The only place troubleshooting is mentioned is (in the getting started + guide)[https://projectcontour.io/getting-started/#troubleshooting]. It's + worth emphasizing this elsewhere (i.e. a page in the docs or a mention on + the docs landing page). This will help as the project grows and people start + using GitHub as a support portal :) - **New user content**: - - You have a great, clearly labelled [Getting Started](https://projectcontour.io/getting-started/) page, which is awesome! However the getting started guide is fairly high level and doesn't answer some of the following questions: - - What else do I need aside from Contour (i.e. the expectation is that the cluster is running Envoy as well) - - What's the next doc I should read _after_ this to understand Contour and how to customize it for my use case? - + - You have a great, clearly labelled + [Getting Started](https://projectcontour.io/getting-started/) page, which is + awesome! However the getting started guide is fairly high level and doesn't + answer some of the following questions: + - What else do I need aside from Contour (i.e. the expectation is that the + cluster is running Envoy as well) + - What's the next doc I should read _after_ this to understand Contour and + how to customize it for my use case? - **Content maintainability**: - - Your documentation is searchable, which is great! - - However, because there are docs on your site that live _outside_ of the docs directory, the entire site needs to be searchable. - - Moving to Hugo is a huge win if you decide to localize (translate) your content, as it has localization support built in. If you do ever decide to localize your content, it would be best to move the docs out of the code repo. + - Your documentation is searchable, which is great! + - However, because there are docs on your site that live _outside_ of the + docs directory, the entire site needs to be searchable. + - Moving to Hugo is a huge win if you decide to localize (translate) your + content, as it has localization support built in. If you do ever decide to + localize your content, it would be best to move the docs out of the code + repo. - **Content creation processes**: - - Because Contour maintains a Docs+Code monorepo, the [CONTRIBUTING.md](https://github.com/projectcontour/contour/blob/main/CONTRIBUTING.md), [Contributing](https://projectcontour.io/docs/v1.13.1/start-contributing/), and [How we work](https://projectcontour.io/resources/how-we-work/) pages are all centered around code processes. As a content creator: - - If I write documentation, who verifies that it's technically accurate? - - If I'm not a native english speaker, who can I ask for help with grammar and language review? - - If I'm a trained technical writer and want to rearrange, create new, or split existing topics, who do I tag in issues/on Slack for comment? - - As a developer user, how can I ensure that content is accurate and up to date? Are alpha and beta features flagged? What happens when content (+ functionality) gets deprecated or changed in a major way? - - Who reviews documentation PRs? + - Because Contour maintains a Docs+Code monorepo, the + [CONTRIBUTING.md](https://github.com/projectcontour/contour/blob/main/CONTRIBUTING.md), + [Contributing](https://projectcontour.io/docs/v1.13.1/start-contributing/), + and [How we work](https://projectcontour.io/resources/how-we-work/) pages + are all centered around code processes. As a content creator: + - If I write documentation, who verifies that it's technically accurate? + - If I'm not a native english speaker, who can I ask for help with grammar + and language review? + - If I'm a trained technical writer and want to rearrange, create new, or + split existing topics, who do I tag in issues/on Slack for comment? + - As a developer user, how can I ensure that content is accurate and up to + date? Are alpha and beta features flagged? What happens when content (+ + functionality) gets deprecated or changed in a major way? + - Who reviews documentation PRs? ### Recommendations -- **Information Architecture**: - - The main issue with information architecture is titling. - - **The guides section:** Having "Guides" as a top-level section which appears in the nav before documentation is a bit confusing. I recommend having documentation as the second link beside Getting Started. - - **Guide titles**: The content in this section seems to be task/tutorial topics – as such I recommend titling them all using action (-ing) verb phrases. - - Good: "Using Gateway API with Contour" - - Not good: "External Authorization Support" - - **Titles alone are not enough**: I also recommend providing a short description of the content in each guide on the /guides root, to help users decide if the content is relevant to their interests without clicking in. - - **Resources**: There is a resources subsection in the docs and one in the top nav. Both have different content. Either rename the top nav resources section "Videos" or rename the Resources section in the docs something else. - - **Documenting the most common use case**: Either as a tutorial or otherwise, clearly documenting the most common use cases – what's the configuration that _most_ people will use, i.e.? Would be helpful for new users. - - **Reference(s) of YAML key/value pairs in the configuration section:** The [annotations reference](https://projectcontour.io/docs/v1.13.1/config/annotations/) is a good example. Do this for each configuration page, similar to the note at the bottom of the [CORS example](https://projectcontour.io/docs/v1.13.1/config/cors/). This is a small win and a great first issue. - -- **New user content**: - - Work with a technical writer to revise your getting started page to provide a bit more background information about Contour for the true new learner and provide more "next steps" documentation. - - **About Contour**: As mentioned above, working with a technical writer to revise/move some of the content to create a clearer "What is Contour?" section for beginners would be useful. +- **Information Architecture**: + + - The main issue with information architecture is titling. + - **The guides section:** Having "Guides" as a top-level section which appears + in the nav before documentation is a bit confusing. I recommend having + documentation as the second link beside Getting Started. + - **Guide titles**: The content in this section seems to be task/tutorial + topics – as such I recommend titling them all using action (-ing) verb + phrases. + - Good: "Using Gateway API with Contour" + - Not good: "External Authorization Support" + - **Titles alone are not enough**: I also recommend providing a short + description of the content in each guide on the /guides root, to help + users decide if the content is relevant to their interests without + clicking in. + - **Resources**: There is a resources subsection in the docs and one in the + top nav. Both have different content. Either rename the top nav resources + section "Videos" or rename the Resources section in the docs something else. + - **Documenting the most common use case**: Either as a tutorial or otherwise, + clearly documenting the most common use cases – what's the configuration + that _most_ people will use, i.e.? Would be helpful for new users. + - **Reference(s) of YAML key/value pairs in the configuration section:** The + [annotations reference](https://projectcontour.io/docs/v1.13.1/config/annotations/) + is a good example. Do this for each configuration page, similar to the note + at the bottom of the + [CORS example](https://projectcontour.io/docs/v1.13.1/config/cors/). This is + a small win and a great first issue. -- **Content creation processes**: - - Document your content creation processes, answering the questions outlined above. This is a great first issue for a new contributor! +- **New user content**: + - Work with a technical writer to revise your getting started page to provide + a bit more background information about Contour for the true new learner and + provide more "next steps" documentation. + - **About Contour**: As mentioned above, working with a technical writer to + revise/move some of the content to create a clearer "What is Contour?" + section for beginners would be useful. -## Contributor documentation +- **Content creation processes**: + - Document your content creation processes, answering the questions outlined + above. This is a great first issue for a new contributor! +## Contributor documentation -| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | | ✅ | -| Beginner friendly issue backlog | | | | ✅ | | -| “New contributor” getting started content | | | | ✅ | | -| Project governance documentation | | | | | ✅ | +| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | +| ----------------------------------------- | ------------------------------------------------- | --- | -------------------------------- | --- | ----------------------------------------------------------- | +| Communication methods documented | | | | | ✅ | +| Beginner friendly issue backlog | | | | ✅ | | +| “New contributor” getting started content | | | | ✅ | | +| Project governance documentation | | | | | ✅ | ### Comments -On the whole, Project Contour does an excellent job of documenting things for new contributors and making the process as smooth as possible. No major feedback in this area, but some minor suggestions to improve an already good process. +On the whole, Project Contour does an excellent job of documenting things for +new contributors and making the process as smooth as possible. No major feedback +in this area, but some minor suggestions to improve an already good process. -Project governance is clearly documented in the community repo, new contributor documentation is clearly signposted on the website, in the docs section of the website, and in the repo. Great job team! +Project governance is clearly documented in the community repo, new contributor +documentation is clearly signposted on the website, in the docs section of the +website, and in the repo. Great job team! -- This is another area where a Docs+Code monorepo might prove difficult to maintain. Because docs issues are interspersed with code issues, it's easy for it to look like there's no code issues. +- This is another area where a Docs+Code monorepo might prove difficult to + maintain. Because docs issues are interspersed with code issues, it's easy for + it to look like there's no code issues. ### Recommendations -- Update [SITE_CONTRIBUTION.md](https://github.com/projectcontour/contour/blob/main/SITE_CONTRIBUTION.md) to Hugo when ready. -- Do a backlog clean of `kind/docuentation` and ensure that all issues are still valid. Close any which are not. For example [this issue](https://github.com/projectcontour/contour/issues/2053) was opened in 2019. -- Improve stub issue descriptions [like this one](https://github.com/projectcontour/contour/issues/2183). A great example of how to write an issue like this without providing too much detail is [this one](https://github.com/kubernetes/website/issues/13864): walk someone new through the steps of thinking through the problem. - +- Update + [SITE_CONTRIBUTION.md](https://github.com/projectcontour/contour/blob/main/SITE_CONTRIBUTION.md) + to Hugo when ready. +- Do a backlog clean of `kind/docuentation` and ensure that all issues are still + valid. Close any which are not. For example + [this issue](https://github.com/projectcontour/contour/issues/2053) was opened + in 2019. +- Improve stub issue descriptions + [like this one](https://github.com/projectcontour/contour/issues/2183). A + great example of how to write an issue like this without providing too much + detail is [this one](https://github.com/kubernetes/website/issues/13864): walk + someone new through the steps of thinking through the problem. ## Website - -| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | -| --- | --- | --- | --- | --- | --- | -| Branding and design | | | | | ✅ | -| Case studies/social proof | | | | ✅ | | -| Maintenance planning | | | ✅ | | | +| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | +| ------------------------- | ------------------------------------------------- | --- | -------------------------------- | --- | ----------------------------------------------------------- | +| Branding and design | | | | | ✅ | +| Case studies/social proof | | | | ✅ | | +| Maintenance planning | | | ✅ | | | ### Comments -- **Branding and design**: The Project Contour website looks very professional and consistently branded! No major improvements needed. +- **Branding and design**: The Project Contour website looks very professional + and consistently branded! No major improvements needed. -- **Case studies/social proof**: Project Contour's [resources page](https://projectcontour.io/resources/) lists a number of great talks given on the project and shows that it's an active member of the cloud native community. While ideally we would see a logo wall of users or case studies, for a project of contour's size this is a great addition to the site. +- **Case studies/social proof**: Project Contour's + [resources page](https://projectcontour.io/resources/) lists a number of great + talks given on the project and shows that it's an active member of the cloud + native community. While ideally we would see a logo wall of users or case + studies, for a project of contour's size this is a great addition to the site. -- **Maitenence planning**: - - **Monorepos**: Having a docs+code monorepo is risky in the long term, as it couples all docs builds with code builds and vice versa. If docs CI fails because Netlify is temporarily down, for example, this means that all your code builds can potentially fail as well. Coupling docs in a repository with code can also make a code repo's size expand exponentially, especially as projects pick up steam, write more blog posts (with images), and add other multimedia. +- **Maitenence planning**: + - **Monorepos**: Having a docs+code monorepo is risky in the long term, as it + couples all docs builds with code builds and vice versa. If docs CI fails + because Netlify is temporarily down, for example, this means that all your + code builds can potentially fail as well. Coupling docs in a repository with + code can also make a code repo's size expand exponentially, especially as + projects pick up steam, write more blog posts (with images), and add other + multimedia. ### Recommendations -- **Branding and design**: one extremely small styling suggestion which would make a great first issue: - - for `

` elements on documentation pages, change the margin from `margin-bottom: 2rem` to `margin-top: 1rem; margin-bottom: 1rem` or (preferred) `margin-top: 1.5rem; margin-bottom: 0.5rem;`. In general it's better to have padding above an h2 rather than below it, as this helps separate each section of a page. +- **Branding and design**: one extremely small styling suggestion which would + make a great first issue: -- **Maitenence planning**: Unless you have very good reasons for staying in a docs+code monorepo, we strongly suggest migrating documentation to its own repository and maintaining it separately. + - for `

` elements on documentation pages, change the margin from + `margin-bottom: 2rem` to `margin-top: 1rem; margin-bottom: 1rem` or + (preferred) `margin-top: 1.5rem; margin-bottom: 0.5rem;`. In general it's + better to have padding above an h2 rather than below it, as this helps + separate each section of a page. +- **Maitenence planning**: Unless you have very good reasons for staying in a + docs+code monorepo, we strongly suggest migrating documentation to its own + repository and maintaining it separately. ## Final Recommendations ### Revamping documentation for new users and new contributors -1. Revise the [docs landing page](https://projectcontour.io/docs/v1.13.1/) to explain the project to a brand new user who has no context on Envoy, Project Contour, or the concept of an ingress controller. +1. Revise the [docs landing page](https://projectcontour.io/docs/v1.13.1/) to + explain the project to a brand new user who has no context on Envoy, Project + Contour, or the concept of an ingress controller. -2. Revise the [getting started page](https://projectcontour.io/getting-started/). Ensure that there is a proper prerequisites list and that new users know where to go next. +2. Revise the + [getting started page](https://projectcontour.io/getting-started/). Ensure + that there is a proper prerequisites list and that new users know where to go + next. -3. Document (or otherwise highlight) a new user's "happy path". Is there a particular configuration or deployment that you think most users will use? How can we highlight this? +3. Document (or otherwise highlight) a new user's "happy path". Is there a + particular configuration or deployment that you think most users will use? + How can we highlight this? -4. Either revise [SITE_CONTRIBUTION.md](https://github.com/projectcontour/contour/blob/main/SITE_CONTRIBUTION.md), [CONTRIBUTING.md](https://github.com/projectcontour/contour/blob/main/CONTRIBUTING.md), [Contributing](https://projectcontour.io/docs/v1.13.1/start-contributing/), and [How we work](https://projectcontour.io/resources/how-we-work/) or create a new section for documentation guidelines. +4. Either revise + [SITE_CONTRIBUTION.md](https://github.com/projectcontour/contour/blob/main/SITE_CONTRIBUTION.md), + [CONTRIBUTING.md](https://github.com/projectcontour/contour/blob/main/CONTRIBUTING.md), + [Contributing](https://projectcontour.io/docs/v1.13.1/start-contributing/), + and [How we work](https://projectcontour.io/resources/how-we-work/) or create + a new section for documentation guidelines. -5. Develop an escalation path for documentation: who approves, who reviews for language, and where can writers ask for help? +5. Develop an escalation path for documentation: who approves, who reviews for + language, and where can writers ask for help? -6. Revise or otherwise use the content on [Contour Philosophy](https://projectcontour.io/resources/philosophy/) as a part of a new getting started guide. +6. Revise or otherwise use the content on + [Contour Philosophy](https://projectcontour.io/resources/philosophy/) as a + part of a new getting started guide. The revised content could have the following structure, if desired: -- Getting started guide: - - Introduction to Project Contour - - Project philosophy - - Why choose Contour over another (less opinionated) ingress controller - - Prerequisites - - Quickstart (getting up and running) - - Setting up a kind cluster - - - - Configuring Contour (in a nutshell) - - Next steps - - Deploying Contour (in a nutshell) - - Next steps - - Where to ask for more help with using Contour - - Next steps +- Getting started guide: -- New contributor guide: - - Where to start - - How we work - - Filing and working on issues for the project - - Where the community is (contacts, meetings) - - Contributing to docs - - Where to ask for more help contributing + - Introduction to Project Contour + - Project philosophy + - Why choose Contour over another (less opinionated) ingress controller + - Prerequisites + - Quickstart (getting up and running) + - Setting up a kind cluster + - + - Configuring Contour (in a nutshell) - Next steps + - Deploying Contour (in a nutshell) + - Next steps + - Where to ask for more help with using Contour + - Next steps +- New contributor guide: + - Where to start + - How we work + - Filing and working on issues for the project + - Where the community is (contacts, meetings) + - Contributing to docs + - Where to ask for more help contributing + - Next steps -### Moving the website into its own repository - -Docs+Code combined repositories are a long-term risk. We strongly recommend decoupling these into their own repositories. - +### Moving the website into its own repository -1. Figure out any code-related dependencies, i.e. API documentation that might be autogenerated, and figure out how to decouple this. +Docs+Code combined repositories are a long-term risk. We strongly recommend +decoupling these into their own repositories. -2. Create a separate documentation repository and move the Netlify configuration & docs code into it. +1. Figure out any code-related dependencies, i.e. API documentation that might + be autogenerated, and figure out how to decouple this. -3. Develop a maintainers list/maintenance plan for the documentation and its repository. +2. Create a separate documentation repository and move the Netlify configuration + & docs code into it. +3. Develop a maintainers list/maintenance plan for the documentation and its + repository. diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md index b1037ff..9ddcc4f 100644 --- a/analyses/0002-notary-project.md +++ b/analyses/0002-notary-project.md @@ -5,115 +5,170 @@ Project: [Notary Project](https://github.com/notaryproject/) ## Introduction -This is an assessment of the Notary Project's documentation, prepared by the CNCF techdocs team. +This is an assessment of the Notary Project's documentation, prepared by the +CNCF techdocs team. This document: - Measures existing documentation quality against the CNCF’s standards - Recommends specific and general improvements -- Provides examples of great documentation as reference +- Provides examples of great documentation as reference - Identifies key improvements with the largest return on investment -Since the Notary Project documentation site is just beginning, and since V2 is still in specification stage, the content will need to be developed (or redeveloped from V1 documentation where available/appropriate). This assessment aims to provide a starting point for that documentation creation process. +Since the Notary Project documentation site is just beginning, and since V2 is +still in specification stage, the content will need to be developed (or +redeveloped from V1 documentation where available/appropriate). This assessment +aims to provide a starting point for that documentation creation process. ## How this document works -This assessment is divided into two sections: +This assessment is divided into two sections: -- **Project documentation:** for end users of the project; aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project +- **Project documentation:** for end users of the project; aimed at people who + intend to use it +- **Contributor documentation:** for new and existing contributors to the + project Each section rates content based on different [criteria](criteria.md). -Normally, a **website** section would also be a part of a document assessment, but as there isn't a website for the Notary Project yet, the website assessment section will be skipped, but there are some website recommendations in the [Final Recommendations](#final-recommendations) section. +Normally, a **website** section would also be a part of a document assessment, +but as there isn't a website for the Notary Project yet, the website assessment +section will be skipped, but there are some website recommendations in the +[Final Recommendations](#final-recommendations) section. - -## Project documentation +## Project documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | +| -------------------------- | --- | --- | --- | --- | --- | | Information architecture | | ✅ | | | | | New user content | ✅ | | | | | | Content maintainability | ✅ | | | | | | Content creation processes | ✅ | | | | | - Criteria: - - 1 = (Is not present or requires significant work) - - 3 = (is present, but needs work) - - 5 = (is executed extremely well or no improvement required) | +Criteria: + +- 1 = (Is not present or requires significant work) +- 3 = (is present, but needs work) +- 5 = (is executed extremely well or no improvement required) | ### Comments #### Information Architecture -- Documentation is currently in several locations and will need to be brought into one repo. The current resources are: - - [The Update Framework Notary repository docs](https://github.com/theupdateframework/notary/tree/master/docs) - - [The Notary Project notaryproject repository](https://github.com/notaryproject/notaryproject) - - [Notary V2 prototype cli](https://github.com/notaryproject/nv2) -- The [V1 Notary Overview](https://github.com/theupdateframework/notary#overview) is reasonable and explanatory. -- The [Notary V2 Overview](https://github.com/notaryproject/notaryproject#notary-v2-overview) provides a good explanation of the V2 project, but which is aimed at the specification writers/developers. - -- Is the documentation feature complete, as in each product feature is documented? - - As the project is in ongoing development, not every feature is completed and so there are some holes in the documentation. - - The [https://github.com/notaryproject/nv2](https://github.com/notaryproject/nv2) repository contains the nv2 prototype cli as well as the documentation about how to use it. Again, since the project is in development it seems like there are some holes. - -- Are there step-by-step instructions (tasks, tutorials) documented for features? - - Since V2's documentation is so conceptual at this point (consisting mostly of specification), it may be best to leave it as is — linking to it directly during the development process, and planning documentation along side the development of the system as a whole. +- Documentation is currently in several locations and will need to be brought + into one repo. The current resources are: + - [The Update Framework Notary repository docs](https://github.com/theupdateframework/notary/tree/master/docs) + - [The Notary Project notaryproject repository](https://github.com/notaryproject/notaryproject) + - [Notary V2 prototype cli](https://github.com/notaryproject/nv2) +- The + [V1 Notary Overview](https://github.com/theupdateframework/notary#overview) is + reasonable and explanatory. +- The + [Notary V2 Overview](https://github.com/notaryproject/notaryproject#notary-v2-overview) + provides a good explanation of the V2 project, but which is aimed at the + specification writers/developers. + +- Is the documentation feature complete, as in each product feature is + documented? + + - As the project is in ongoing development, not every feature is completed and + so there are some holes in the documentation. + - The + [https://github.com/notaryproject/nv2](https://github.com/notaryproject/nv2) + repository contains the nv2 prototype cli as well as the documentation about + how to use it. Again, since the project is in development it seems like + there are some holes. + +- Are there step-by-step instructions (tasks, tutorials) documented for + features? + + - Since V2's documentation is so conceptual at this point (consisting mostly + of specification), it may be best to leave it as is — linking to it + directly during the development process, and planning documentation along + side the development of the system as a whole. - Is the “happy path”/most common use case documented? - - The V1 Getting Started Guide is very good. Will V2 be able to draw from it? -- If the documentation does not suffice, is there a clear escalation path for users needing more help, such as an FAQ or Troubleshooting section? - - This is an area for improvement on both V1 and V2 docs. Potentially consider reorganizing the whole docset with users in mind: dividing the content in a concepts, tasks, and tutorials model. + - The V1 Getting Started Guide is very good. Will V2 be able to draw from it? + +- If the documentation does not suffice, is there a clear escalation path for + users needing more help, such as an FAQ or Troubleshooting section? + - This is an area for improvement on both V1 and V2 docs. Potentially consider + reorganizing the whole docset with users in mind: dividing the content in a + concepts, tasks, and tutorials model. #### New user content -- Getting Started Guide is clearly labelled: [https://github.com/theupdateframework/notary#getting-started-with-the-notary-cli](https://github.com/theupdateframework/notary#getting-started-with-the-notary-cli) though notably only in v1 of their docs, not v2. How does one get started with v2? -- The v2 overview has getting started/CLI steps for an entirely different set of functions: [https://github.com/notaryproject/notaryproject#notary-v2-overview](https://github.com/notaryproject/notaryproject#notary-v2-overview). Are these in addition to or in replacement of the v1 getting started steps? -- Where do users go after the getting started steps? Is there anything else about the tool they need to understand? +- Getting Started Guide is clearly labelled: + [https://github.com/theupdateframework/notary#getting-started-with-the-notary-cli](https://github.com/theupdateframework/notary#getting-started-with-the-notary-cli) + though notably only in v1 of their docs, not v2. How does one get started with + v2? +- The v2 overview has getting started/CLI steps for an entirely different set of + functions: + [https://github.com/notaryproject/notaryproject#notary-v2-overview](https://github.com/notaryproject/notaryproject#notary-v2-overview). + Are these in addition to or in replacement of the v1 getting started steps? +- Where do users go after the getting started steps? Is there anything else + about the tool they need to understand? - Sample code looks great! #### Content maintainability -- As the documentation is in GitHub it is searchable. When setting up a website, we recommend using Google, Algolia, or Lunr to provide search functionality. - -- Is the Notary Project planning on localization/internationalization? If so, we recommend starting the site with a directory structure which supports localization (Hugo supports this very well out of the box). +- As the documentation is in GitHub it is searchable. When setting up a website, + we recommend using Google, Algolia, or Lunr to provide search functionality. +- Is the Notary Project planning on localization/internationalization? If so, we + recommend starting the site with a directory structure which supports + localization (Hugo supports this very well out of the box). -- Is any of the content from v1 relevant to v2? - - If so, import v1 into the site, and "version" by copying the content into a new directory for v2 and updating only what needs to change or be added. - - If not, upload v1 and v2 into the site as separate document sets. +- Is any of the content from v1 relevant to v2? + - If so, import v1 into the site, and "version" by copying the content into a + new directory for v2 and updating only what needs to change or be added. + - If not, upload v1 and v2 into the site as separate document sets. #### Content creation processes -- The following are ideas to consider going forward with a docs repo. As a content creator: - - If I write documentation, who verifies that it's technically accurate? - - If I'm not a native english speaker, who can I ask for help with grammar and language review? - - If I'm a trained technical writer and want to rearrange, create new, or split existing topics, who do I tag in issues/on Slack for comment? - - As a developer user, how can I ensure that content is accurate and up to date? Are alpha and beta features flagged? What happens when content (+ functionality) gets deprecated or changed in a major way? - - Who reviews documentation PRs? + +- The following are ideas to consider going forward with a docs repo. As a + content creator: + - If I write documentation, who verifies that it's technically accurate? + - If I'm not a native english speaker, who can I ask for help with grammar and + language review? + - If I'm a trained technical writer and want to rearrange, create new, or + split existing topics, who do I tag in issues/on Slack for comment? + - As a developer user, how can I ensure that content is accurate and up to + date? Are alpha and beta features flagged? What happens when content (+ + functionality) gets deprecated or changed in a major way? + - Who reviews documentation PRs? ### Recommendations #### Information Architecture -The assumption is that V2 is the primary project moving forward, and that a Minimum Viable Product (MVP) for a website/documentation will focus on Notary V2 users. -- Bring the Notary v2 CLI prototype documentation into the main documentation when consolidating the content on the website. -- Rework the v1 Docs once an information architecture (IA) is set up for the new site. Set up the new site IA based on the structure of the v1 docs unless an alternative is proposed. +The assumption is that V2 is the primary project moving forward, and that a +Minimum Viable Product (MVP) for a website/documentation will focus on Notary V2 +users. -- Separate specifications from user-centered documentation. For example, how [Service Mesh Interface website](https://smi-spec.io/) handles its specification. +- Bring the Notary v2 CLI prototype documentation into the main documentation + when consolidating the content on the website. +- Rework the v1 Docs once an information architecture (IA) is set up for the new + site. Set up the new site IA based on the structure of the v1 docs unless an + alternative is proposed. +- Separate specifications from user-centered documentation. For example, how + [Service Mesh Interface website](https://smi-spec.io/) handles its + specification. -## Contributor documentation +## Contributor documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | +| ----------------------------------------- | --- | --- | --- | --- | --- | | Communication methods documented | | | ✅ | | | | Beginner friendly issue backlog | | ✅ | | | | | “New contributor” getting started content | ✅ | | | | | | Project governance documentation | ✅ | | | | | -Criteria +Criteria + - 1 = (Is not present or requires significant work) - 3 = (is present, but needs work) - 5 = (is executed extremely well or no improvement required) | @@ -121,75 +176,107 @@ Criteria ### Comments & recommendations - Most of the issues in this section are a function of not having a website yet. - - As the website build process starts, put together a skeleton IA that can be filled in as the project grows. -- Communication methods are documented but could be further centralized and expanded during the site development process, with an end result comparable to https://prometheus.io/community/. + - As the website build process starts, put together a skeleton IA that can be + filled in as the project grows. + +- Communication methods are documented but could be further centralized and + expanded during the site development process, with an end result comparable to + https://prometheus.io/community/. - There is no documentation for: - - Triaging docs issues - - Clearly marking a way for new contributors to make code or documentation contributions (i.e. a “good first issue” label), and define what makes a good first issue - - Set up a process for maintaining/pruning stale issues - - New contributors/your first contribution - - Letting new users know where to get help -- Complete the governance work started here: https://github.com/notaryproject/notaryproject/issues/55 https://github.com/notaryproject/notaryproject/pull/78, and add it to a governance page (or section) on the website. + - Triaging docs issues + - Clearly marking a way for new contributors to make code or documentation + contributions (i.e. a “good first issue” label), and define what makes a + good first issue + - Set up a process for maintaining/pruning stale issues + - New contributors/your first contribution + - Letting new users know where to get help +- Complete the governance work started here: + https://github.com/notaryproject/notaryproject/issues/55 + https://github.com/notaryproject/notaryproject/pull/78, and add it to a + governance page (or section) on the website. ## Final Recommendations -Is it possible plan documentation along side the V2 development? Will the documentation be able to get its structure from the specifications being developed? +Is it possible plan documentation along side the V2 development? Will the +documentation be able to get its structure from the specifications being +developed? ### Website -- [x] Create separate documentation repository: https://github.com/notaryproject/notaryproject.dev -- [ ] Setup a [Hugo website](https://gohugo.io) with a [Docsy theme](https://www.docsy.dev/) +- [x] Create separate documentation repository: + https://github.com/notaryproject/notaryproject.dev +- [ ] Setup a [Hugo website](https://gohugo.io) with a + [Docsy theme](https://www.docsy.dev/) - [ ] Setup Netlify for hosting/CI -- [ ] Develop a [maintainers list](https://github.com/notaryproject/notaryproject.dev/blob/main/.github/settings.yml) for the documentation and its repository (this has been started https://github.com/notaryproject/notaryproject/issues/77) -- [ ] Develop a maintenance plan for the documentation and its repository -- [ ] Follow the [CNCF website guidelines checklist](https://github.com/cncf/techdocs/blob/main/howto/website-guidelines-checklist.md) for other required elements - -_Note_: [Notary Project branding artwork](https://github.com/cncf/artwork/tree/master/projects/notary) exists. Other branding elements, like colour schemes and whatnot, will need to be developed. +- [ ] Develop a + [maintainers list](https://github.com/notaryproject/notaryproject.dev/blob/main/.github/settings.yml) + for the documentation and its repository (this has been started + https://github.com/notaryproject/notaryproject/issues/77) +- [ ] Develop a maintenance plan for the documentation and its repository +- [ ] Follow the + [CNCF website guidelines checklist](https://github.com/cncf/techdocs/blob/main/howto/website-guidelines-checklist.md) + for other required elements + +_Note_: +[Notary Project branding artwork](https://github.com/cncf/artwork/tree/master/projects/notary) +exists. Other branding elements, like colour schemes and whatnot, will need to +be developed. ### Information Architecture -We recommend reorganizing your content in the following way: +We recommend reorganizing your content in the following way: **Site structure** - Landing page - Community - - Governance - - Community (details) - - Contributing - - Where to start - - How we work - - Filing and working on issues for the project - - Where the community is (contacts, meetings) - - Contributing to docs - - Where to ask for more help contributing - - Next steps + - Governance + - Community (details) + - Contributing + - Where to start + - How we work + - Filing and working on issues for the project + - Where the community is (contacts, meetings) + - Contributing to docs + - Where to ask for more help contributing + - Next steps - About - Blog (Get the word out about the project and how it's progressing) - Docs - - This section to be planned with the Notary Maintainers team - - Getting Started - - This section to be planned with the Notary Maintainers team + - This section to be planned with the Notary Maintainers team + - Getting Started + - This section to be planned with the Notary Maintainers team **Top nav** -- Docs/Specification (Specification initially, then Docs as development progresses) -- Version 1 Docs (https://github.com/theupdateframework/notary/tree/master/docs initially, then /docs/v1/(latest?)) +- Docs/Specification (Specification initially, then Docs as development + progresses) +- Version 1 Docs (https://github.com/theupdateframework/notary/tree/master/docs + initially, then /docs/v1/(latest?)) - Community - Getting started - Specification (https://github.com/notaryproject/notaryproject initially) - ### Moving and consolidating existing documentation -- We recommend moving the v1 Notary Project project from the [The Update Framework](https://github.com/theupdateframework/notary/) GitHub organization to the [Notary Project](https://github.com/notaryproject) GitHub organization. -- Remove any references to Docker (the original home of the documentation), for example "the Docker Notary documentation". -- Even if the V1 Notary repo isn't moved, the website MVP should link to V1 notary where it is now, with no changes. -- Docs+Code combined repositories are a long-term risk. We strongly recommend decoupling these into their own repositories - - As you build the website, move the existing v2 documentation from https://github.com/notaryproject/notaryproject to https://github.com/notaryproject/notaryproject.dev - - Include the Notary v2 CLI prototype documentation (https://github.com/notaryproject/nv2) in this migration - - After building the website MVP, migrate all relevant documentation from v1 to the website/documentation repository. +- We recommend moving the v1 Notary Project project from the + [The Update Framework](https://github.com/theupdateframework/notary/) GitHub + organization to the [Notary Project](https://github.com/notaryproject) GitHub + organization. +- Remove any references to Docker (the original home of the documentation), for + example "the Docker Notary documentation". +- Even if the V1 Notary repo isn't moved, the website MVP should link to V1 + notary where it is now, with no changes. +- Docs+Code combined repositories are a long-term risk. We strongly recommend + decoupling these into their own repositories + - As you build the website, move the existing v2 documentation from + https://github.com/notaryproject/notaryproject to + https://github.com/notaryproject/notaryproject.dev + - Include the Notary v2 CLI prototype documentation + (https://github.com/notaryproject/nv2) in this migration + - After building the website MVP, migrate all relevant documentation from v1 + to the website/documentation repository. diff --git a/analyses/0003-krator.md b/analyses/0003-krator.md index 25cbc22..ed9a954 100644 --- a/analyses/0003-krator.md +++ b/analyses/0003-krator.md @@ -2,185 +2,262 @@ ## Introduction - -This is an assessment of your project documentation and website (if present), prepared for you and your project by the CNCF techdocs team. +This is an assessment of your project documentation and website (if present), +prepared for you and your project by the CNCF techdocs team. This document aims to: - Measure existing documentation quality against the CNCF’s standards - Recommend specific and general improvements -- Provide examples of great documentation as reference -- Identify key areas which will net the largest improvement if addressed +- Provide examples of great documentation as reference +- Identify key areas which will net the largest improvement if addressed -Since the Krator documentation site is just getting started, we'll have to create or significantly develop the current content. This assessment provides a starting point for articulating current state and ideas for the future. +Since the Krator documentation site is just getting started, we'll have to +create or significantly develop the current content. This assessment provides a +starting point for articulating current state and ideas for the future. ## How this document works -The assessment is divided into three sections: +The assessment is divided into three sections: -- **Project documentation:** for end users of the project; aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project +- **Project documentation:** for end users of the project; aimed at people who + intend to use it +- **Contributor documentation:** for new and existing contributors to the + project - **Website:** branding, website structure, and maintainability -Within each section you receive a rating on different criteria. The full definition of each criteria is defined in [the criteria](criteria.md). We recommend reading each criterion’s definition. +Within each section you receive a rating on different criteria. The full +definition of each criteria is defined in [the criteria](criteria.md). We +recommend reading each criterion’s definition. -## Project documentation +## Project documentation +| Criteria | 1 | 2 | 3 | 4 | 5 | +| -------------------------- | --- | --- | --- | --- | --- | +| Information architecture | ✅ | | | | | +| New user content | ✅ | | | | | +| Content maintainability | ✅ | | | | | +| Content creation processes | ✅ | | | | | -| Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Information architecture | ✅ | | | | | -| New user content | ✅ | | | | | -| Content maintainability | ✅ | | | | | -| Content creation processes | ✅ | | | | | +Criteria: - Criteria: - - 1 = (Is not present or requires significant work) - - 3 = (is present, but needs work) - - 5 = (is executed extremely well or no improvement required) +- 1 = (Is not present or requires significant work) +- 3 = (is present, but needs work) +- 5 = (is executed extremely well or no improvement required) ### Comments -- **Information Architecture**: - - Documentation is currently in several locations and will need to be brought into one repo. The current resources are: - - The project [README](https://github.com/krator-rs/krator) - - [Introduction to krator Blog Post](https://deislabs.io/posts/introducing-krator/) - - [A Fistful of States: More State Machine Patterns in Rust](https://deislabs.io/posts/a-fistful-of-states/) - - [Crate krator API Documentation](https://docs.rs/krator/0.4.0/krator/). This is a substantial part of the current documentation and could be incorporated into the main body (site/repo) of the documentation. This is already a great resource for users, but if we transport it to a documentation repo, it will take some work if it's not already in markdown. Is there a way extract/download these guides quickly? Another important consideration is that because the API documentation is auto-generated as a part of the Rust Crate, documenting these features is convenient for the developers, however, it is more challenging for non-developer users to contribute to the documentation. We recommend that the Krator team determine which path is best in the long term. If we choose to pull the API documentation into the docs repo, there's more up front work, however, the benefit is more potential community engagement. - - [GitHub Documentation](https://github.com/krator-rs/krator/tree/main/docs). The Community guides teach contributing and development. - - The [Developer Guide](https://github.com/krator-rs/krator/blob/main/docs/community/developers.md) covers prerequisites and building, which would make a good introductory or Getting Started entry point. - - The [Release Checklist](https://github.com/krator-rs/krator/blob/main/docs/community/release-checklist.md) appears aimed at developers of Krator, as opposed to first-time users. This should ideally be separated from the entry point. +- **Information Architecture**: + + - Documentation is currently in several locations and will need to be brought + into one repo. The current resources are: + - The project [README](https://github.com/krator-rs/krator) + - [Introduction to krator Blog Post](https://deislabs.io/posts/introducing-krator/) + - [A Fistful of States: More State Machine Patterns in Rust](https://deislabs.io/posts/a-fistful-of-states/) + - [Crate krator API Documentation](https://docs.rs/krator/0.4.0/krator/). + This is a substantial part of the current documentation and could be + incorporated into the main body (site/repo) of the documentation. This is + already a great resource for users, but if we transport it to a + documentation repo, it will take some work if it's not already in + markdown. Is there a way extract/download these guides quickly? Another + important consideration is that because the API documentation is + auto-generated as a part of the Rust Crate, documenting these features is + convenient for the developers, however, it is more challenging for + non-developer users to contribute to the documentation. We recommend that + the Krator team determine which path is best in the long term. If we + choose to pull the API documentation into the docs repo, there's more up + front work, however, the benefit is more potential community engagement. + - [GitHub Documentation](https://github.com/krator-rs/krator/tree/main/docs). + The Community guides teach contributing and development. + - The + [Developer Guide](https://github.com/krator-rs/krator/blob/main/docs/community/developers.md) + covers prerequisites and building, which would make a good introductory + or Getting Started entry point. + - The + [Release Checklist](https://github.com/krator-rs/krator/blob/main/docs/community/release-checklist.md) + appears aimed at developers of Krator, as opposed to first-time users. + This should ideally be separated from the entry point. - **New user content**: - - We'll need to create a clear entry point for the new user. Some of this info could be taken from the [Developer Guide](https://github.com/krator-rs/krator/blob/main/docs/community/developers.md) and includes prerequisite knowlege, configuration, and a brief step-by-step guide on adding Krator to your project. - + - We'll need to create a clear entry point for the new user. Some of this info + could be taken from the + [Developer Guide](https://github.com/krator-rs/krator/blob/main/docs/community/developers.md) + and includes prerequisite knowlege, configuration, and a brief step-by-step + guide on adding Krator to your project. - **Content maintainability**: - - Since we'll be creating a site, search doesn't apply yet (though will be part of the basic site). - - Using Hugo will add the benefit of localization support. + - Since we'll be creating a site, search doesn't apply yet (though will be + part of the basic site). + - Using Hugo will add the benefit of localization support. + - **Content creation processes**: - - The following are ideas to consider going forward with a docs repo. As a content creator: - - If I write documentation, who verifies that it's technically accurate? - - If I'm not a native english speaker, who can I ask for help with grammar and language review? - - If I'm a trained technical writer and want to rearrange, create new, or split existing topics, who do I tag in issues/on Slack for comment? - - As a developer user, how can I ensure that content is accurate and up to date? Are alpha and beta features flagged? What happens when content (+ functionality) gets deprecated or changed in a major way? - - Who reviews documentation PRs? + - The following are ideas to consider going forward with a docs repo. As a + content creator: + - If I write documentation, who verifies that it's technically accurate? + - If I'm not a native english speaker, who can I ask for help with grammar + and language review? + - If I'm a trained technical writer and want to rearrange, create new, or + split existing topics, who do I tag in issues/on Slack for comment? + - As a developer user, how can I ensure that content is accurate and up to + date? Are alpha and beta features flagged? What happens when content (+ + functionality) gets deprecated or changed in a major way? + - Who reviews documentation PRs? ### Recommendations -- **Information Architecture**: - The main task with information architecture is conceptualization and development as the documents are currently in different places. The following areas would establish a foundation: - - **About Krator:** Give a high-level view of Krator and what it solves. - **Most common use case(s)** - - **A Quickstart or Getting Started:** Having an obvious starting point as a top-level section or doc gives new visitors a sense of context. I recommend creating a Getting Started/Quickstart. - - **Tutorials** - - **Setting up Krator** - - **Configuring your project to use krator** - - **Tasks:** I recommend a section with step-by-step instructions on how to accomplish the most common tasks in Krator. For example, if you have five most common tasks, you could have a document for each. Suggestions include: - - **Using built-in operators** - - **Creating your own operators with krator** - - Are there other common tasks? If so, they should go here. - - **Best practices** +- **Information Architecture**: The main task with information architecture is + conceptualization and development as the documents are currently in different + places. The following areas would establish a foundation: + - **About Krator:** Give a high-level view of Krator and what it solves. + **Most common use case(s)** + - **A Quickstart or Getting Started:** Having an obvious starting point as a + top-level section or doc gives new visitors a sense of context. I recommend + creating a Getting Started/Quickstart. + - **Tutorials** + - **Setting up Krator** + - **Configuring your project to use krator** + - **Tasks:** I recommend a section with step-by-step instructions on how to + accomplish the most common tasks in Krator. For example, if you have five + most common tasks, you could have a document for each. Suggestions include: + - **Using built-in operators** + - **Creating your own operators with krator** + - Are there other common tasks? If so, they should go here. + - **Best practices** + - **Troubleshooting** - **Troubleshooting** - - **Troubleshooting** - - **Error Reference** A table with explanations and resolution steps would suffice - - **Contributing to krator** - - **Cutting releases** (This is existing documentation) - - **Contributing:** Include information on submitting issues and instructions with links on contributing to the code base and to the documentation. - - **API Documentation:** If you choose to bring this into the main documentation repo, the copy will need to be ported. Is the content available in markdown already? If not, it will need to be converted. - -## Contributor documentation - -| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | ✅ | | | | | -| Beginner friendly issue backlog | ✅ | | | | | -| “New contributor” getting started content | ✅ | | | | | -| Project governance documentation | ✅ | | | | | + - **Error Reference** A table with explanations and resolution steps would + suffice + - **Contributing to krator** + - **Cutting releases** (This is existing documentation) + - **Contributing:** Include information on submitting issues and + instructions with links on contributing to the code base and to the + documentation. + - **API Documentation:** If you choose to bring this into the main + documentation repo, the copy will need to be ported. Is the content + available in markdown already? If not, it will need to be converted. + +## Contributor documentation + +| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | +| ----------------------------------------- | ------------------------------------------------- | --- | -------------------------------- | --- | ----------------------------------------------------------- | +| Communication methods documented | ✅ | | | | | +| Beginner friendly issue backlog | ✅ | | | | | +| “New contributor” getting started content | ✅ | | | | | +| Project governance documentation | ✅ | | | | | ### Comments and recommendations -Communication methods will need to be determined and added to [CONTRIBUTING.md](https://github.com/krator-rs/krator/blob/main/CONTRIBUTING.md). - -While there is an issue backlog, there aren't any issues with a `good first issue` label. As an invitation to new contributors, consider filing issues that are easy to remedy, labeling them accordingly, posting them on social media, and being available to help contributors through the process. +Communication methods will need to be determined and added to +[CONTRIBUTING.md](https://github.com/krator-rs/krator/blob/main/CONTRIBUTING.md). -There is a brief mention of the PR review process in [CONTRIBUTING.md](https://github.com/krator-rs/krator/blob/main/CONTRIBUTING.md), however, giving more detail about the process, such as rounds of review, time frame, a link to [CODEOWNERS](https://github.com/krator-rs/krator/blob/main/CODEOWNERS), tests that have to pass, etc. help manage contributor expectations. This, along with linking to the Code of Conduct as you currently do, establishes a context for new contributors. - -In terms of governance, the Krator maintainers have an issue open for adopting Open Governance. When this is complete, we'd advise bringing it into the documentation. +While there is an issue backlog, there aren't any issues with a +`good first issue` label. As an invitation to new contributors, consider filing +issues that are easy to remedy, labeling them accordingly, posting them on +social media, and being available to help contributors through the process. +There is a brief mention of the PR review process in +[CONTRIBUTING.md](https://github.com/krator-rs/krator/blob/main/CONTRIBUTING.md), +however, giving more detail about the process, such as rounds of review, time +frame, a link to +[CODEOWNERS](https://github.com/krator-rs/krator/blob/main/CODEOWNERS), tests +that have to pass, etc. help manage contributor expectations. This, along with +linking to the Code of Conduct as you currently do, establishes a context for +new contributors. +In terms of governance, the Krator maintainers have an issue open for adopting +Open Governance. When this is complete, we'd advise bringing it into the +documentation. ## Website -| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | -| --- | --- | --- | --- | --- | --- | -| Branding and design | ✅ | | | | | -| Case studies/social proof | ✅ | | | | | -| Maintenance planning | ✅ | | | | | +| Criteria | 1 = (Is not present or requires significant work) | 2 | 3 = (is present, but needs work) | 4 | 5 = (is executed extremely well or no improvement required) | +| ------------------------- | ------------------------------------------------- | --- | -------------------------------- | --- | ----------------------------------------------------------- | +| Branding and design | ✅ | | | | | +| Case studies/social proof | ✅ | | | | | +| Maintenance planning | ✅ | | | | | ### Comments -Note: as Krator does not have a website yet, we did not expect any of these to be done! +Note: as Krator does not have a website yet, we did not expect any of these to +be done! -- **Branding and design**: When the logo is ready, we'll be able to select colors, typically inspired by the logo, for backgrounds, links, and design elements such as borders. -Sometimes Krator is capitalized, yet other times lowercase. I would recommend using one or the other consistently. +- **Branding and design**: When the logo is ready, we'll be able to select + colors, typically inspired by the logo, for backgrounds, links, and design + elements such as borders. Sometimes Krator is capitalized, yet other times + lowercase. I would recommend using one or the other consistently. -- **Case studies/social proof**: As you develop Krator, keep an eye out for companies and projects using Krator, and start working with them early to do things like write blog posts about their experiences. -As you gather user blog posts over time, submit a ticket to the CNCF Service Desk and we can turn these into a more marketing-friendly case studies section on your site. +- **Case studies/social proof**: As you develop Krator, keep an eye out for + companies and projects using Krator, and start working with them early to do + things like write blog posts about their experiences. As you gather user blog + posts over time, submit a ticket to the CNCF Service Desk and we can turn + these into a more marketing-friendly case studies section on your site. -- **Maitenence planning**: - - **Monorepos**: Having a docs+code monorepo is risky in the long term, as it couples all docs builds with code builds and vice versa. If docs CI fails because Netlify is temporarily down, for example, this means that all your code builds can potentially fail as well. Coupling docs in a repository with code can also make a code repo's size expand exponentially, especially as projects pick up steam, write more blog posts (with images), and add other multimedia. For these reasons, we recommend housing the documentation in a separate repo. + +- **Maitenence planning**: + - **Monorepos**: Having a docs+code monorepo is risky in the long term, as it + couples all docs builds with code builds and vice versa. If docs CI fails + because Netlify is temporarily down, for example, this means that all your + code builds can potentially fail as well. Coupling docs in a repository with + code can also make a code repo's size expand exponentially, especially as + projects pick up steam, write more blog posts (with images), and add other + multimedia. For these reasons, we recommend housing the documentation in a + separate repo. ## Final Recommendations ### Creating documentation for new users and new contributors -1. Create a landing page that distills at-a-glance how Krator makes the world a better place, how easy it is to use, and how supportive the community is. +1. Create a landing page that distills at-a-glance how Krator makes the world a + better place, how easy it is to use, and how supportive the community is. 1. Create an About page or blog post that tells the Krator back story. -1. One of the most important areas for a documentation site is the Getting Started guide. I'd recommend an introductory page that explains what Krator does and why it was created that a beginner developer could understand. - -1. Create a document that shows, step-by-step, how to start using Krator. Provide prerequisites so that potential adopters can know at a glance if adoption is feasible for their circumstances. +1. One of the most important areas for a documentation site is the Getting + Started guide. I'd recommend an introductory page that explains what Krator + does and why it was created that a beginner developer could understand. -1. Document common use cases and give examples, with code on the page (ideally from a linked, working example). +1. Create a document that shows, step-by-step, how to start using Krator. + Provide prerequisites so that potential adopters can know at a glance if + adoption is feasible for their circumstances. +1. Document common use cases and give examples, with code on the page (ideally + from a linked, working example). Consider a structure as in the following: - Site landing page - - Why Krator makes life easier - - Ease of use - - Community (blog link, social media, logos) -- About (origin story: who, where, when, why) -- Getting started - - Introduction to Krator - - Project philosophy - - Prerequisites - - Quickstart + - Why Krator makes life easier + - Ease of use + - Community (blog link, social media, logos) +- About (origin story: who, where, when, why) +- Getting started + - Introduction to Krator + - Project philosophy + - Prerequisites + - Quickstart - Tutorials - - Configuring Krator - - Next steps - - Deploying Krator - - Next steps - - Where to get support when using Krator - - Next steps + - Configuring Krator + - Next steps + - Deploying Krator + - Next steps + - Where to get support when using Krator + - Next steps - Tasks - - Using built-in operators - - Creating your own operators with Krator + - Using built-in operators + - Creating your own operators with Krator - Best practices - Troubleshooting - - Error reference if applicable + - Error reference if applicable - API documentation - Contributing - - New contributor guide: - - Where to start - - How we work - - Filing and working on issues for the project - - Where the community is (contacts, meetings) - - Contributing to docs - - Where to ask for more help contributing - - Next steps - - Cutting releases \ No newline at end of file + - New contributor guide: + - Where to start + - How we work + - Filing and working on issues for the project + - Where the community is (contacts, meetings) + - Contributing to docs + - Where to ask for more help contributing + - Next steps + - Cutting releases diff --git a/analyses/0004-tremor.md b/analyses/0004-tremor.md index 97ffac9..7365447 100644 --- a/analyses/0004-tremor.md +++ b/analyses/0004-tremor.md @@ -1,172 +1,317 @@ -# Assessment: Project Tremor +# Assessment: Project Tremor -Prepared by: Celeste Horgan -Date: July 2021 +Prepared by: Celeste Horgan Date: July 2021 ## Introduction -This document assesses the quality and completeness of a project's documentation and website (if present). +This document assesses the quality and completeness of a project's documentation +and website (if present). This document: - Measures existing documentation quality against the CNCF’s standards - Recommends specific and general improvements -- Provides examples of great documentation as reference +- Provides examples of great documentation as reference - Identifies key improvements with the largest return on investment ## How this document works -The assessment is divided into three sections: +The assessment is divided into three sections: -- **Project documentation:** for end users of the project; aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project +- **Project documentation:** for end users of the project; aimed at people who + intend to use it +- **Contributor documentation:** for new and existing contributors to the + project - **Website:** branding, website structure, and maintainability Each section rates content based on different [criteria](criteria.md). -## Project documentation - +## Project documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Information architecture | | ✅ | | | | -| New user content | | ✅ | | | | -| Content maintainability | | ✅ | | | | -| Content creation processes | ✅ | | | | | +| -------------------------- | --- | --- | --- | --- | --- | +| Information architecture | | ✅ | | | | +| New user content | | ✅ | | | | +| Content maintainability | | ✅ | | | | +| Content creation processes | ✅ | | | | | + +Scale: -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** -- **Information Architecture:** Project Tremor's documentation makes a number of individually small IA choices that culminate in a confusing experience for the user. - - The [Getting Started](https://www.tremor.rs/getting-started/) section covers a number of seemingly random topics, with some appearing to be focused on selling the project to new users (i.e. [Good User Experience](https://www.tremor.rs/getting-started/tooling/)), more traditional "getting started" content ([Quick Install](https://www.tremor.rs/getting-started/install/)), and high-level conceptual documentation ([Understanding Data](https://www.tremor.rs/getting-started/codecs/)). - - Tremor has ample high-level conceptual overview information, but it's somewhat scattered. - - The [Architecture Overview - Goodness of fit](https://docs.tremor.rs/overview/) section is probably the best overview for brand new users available, however the rest of the page gets very detailed very quickly, and feels like a collection of semi-random topics that someone felt the need to write down, with no real direction. This page probably needs to be broken up into many pages within a section, with some of the more esoteric topics currently under "Getting Started" included. - - Low-level task content often gets buried in [Recipes](https://docs.tremor.rs/tremor-query/recipes/), generically titled [Walkthrough](https://docs.tremor.rs/operations/configuration-walkthrough/) pages, and the extremely helpful but poorly named [Workshops](https://docs.tremor.rs/workshop/examples/00_passthrough/) section. This makes it hard for a user with a specific query ("How do I do....") to know, at a glance, if the documentation contains the answer to their question or not. - - [The Configuration walkthrough](https://docs.tremor.rs/operations/configuration-walkthrough/) was the single most useful page in terms of understanding the overall 'picture' of what Tremor is and how a developer needs to move through the documentation. But it's buried in the Configuration section, and I wouldn't think to look there until I was much further in the process. - - Given how valuable the [Workshops](https://docs.tremor.rs/workshop/examples/00_passthrough/) section is, it needs a better name. "Recipes", "Tutorials", "How to" would all be clearer. - - Some specific comments about the Tremor Query and Script sections: - - The [Tremor Query Overview](https://docs.tremor.rs/tremor-query/) and [Tremor Script Overview](https://docs.tremor.rs/tremor-script/) would benefit from splitting the "Language" topic and subtopics into their own page in the section. - - As someone unfamiliar with the project, I'm not sure how [Tremor Query](https://docs.tremor.rs/tremor-query/) and [Tremor Script](https://docs.tremor.rs/tremor-script/) are different based purely on their overviews. I'm also not sure if they work together or not, or if I as a user need to use one language versus another. - - Given the complexity of Tremor's various query methods, I think focusing on producing more [Recipes](https://docs.tremor.rs/tremor-script/recipes/) would be a helpful next step for the team. - - [History](https://docs.tremor.rs/history/) probably doesn't belong as a top-level section. - - [Development](https://docs.tremor.rs/development/) and [Governance](https://docs.tremor.rs/CodeOfConduct/) are targeted at contributor users rather than end users, and should be in a different section of the site if possible. - -- **New user content:** Project Tremor has a Getting Started section but it's a little disorganized as mentioned above. This makes it difficult for an actual new user to understand. - - [Starting Tremor for the first time](https://www.tremor.rs/getting-started/starting/) is the best part of the getting started guide. However, it mentions that there are "many ways" to install Tremor - it would be good to point users to documentation on those other ways of installing. - - Is the [Quick developer install](https://www.tremor.rs/getting-started/install/) the "other methods"? There's no introduction to this page, so I can't tell. - - [Talking to other systems](https://www.tremor.rs/getting-started/connectivity/) is definitely a foundational concept for Tremor (as an events processing system) but the style in which it's written isn't appropriate for a getting started guide. This goes for [Understanding Data](https://www.tremor.rs/getting-started/codecs/), [Scripting](https://www.tremor.rs/getting-started/scripting/) and [Specialize Tremor Pipelines](https://www.tremor.rs/getting-started/specialize/). - - These topics should be under Docs in their own section, perhaps titled "Overview". - - Ensuring that all pages, like [The Tremor CLI tool](https://docs.tremor.rs/operations/cli/), have overviews goes a long way in ensuring the docs are user friendly for new users. - - I like the [FAQ](https://www.tremor.rs/faq/) as new user content, but FAQs often become a catch-all and get messy quickly. Proceed with caution. - -- **Content maintainability:** - - Docs are mostly separated into their own repository, https://github.com/tremor-rs/tremor-www-docs, though as the maintainers note there are many other repositories with docs available in them. These need to be consolidated for easier maintenance. - - The [scripts](https://github.com/tremor-rs/tremor-www-docs/tree/main/python_scripts) which generate certain pieces of documentation introduce fragility into the system: if the location of files, names of repos, etc. change then the documentation pipeline breaks. This also makes it hard for non-"technical" users to make changes to these pages, and to reorganize these pages if needed. - - The automation benefits might be worth it however. - - Your [release process](https://github.com/tremor-rs/tremor-www-docs/blob/main/RELEASE_PROCESS.md) is documented, which is great to see! - - Your site is only partially searchable, with sections not within /docs inaccessible by search. - -- **Content creation processes:** There are no content creation processes documented and no CONTRIBUTING.md file for the main docs repository. Some things to think about: - - If I write documentation, who verifies that it's technically accurate? - - If I'm not a native English speaker, who can I ask for help with grammar and language review? - - If I'm a trained technical writer and want to rearrange, create new, or split existing topics, who do I tag in issues/on Slack for comment? - - As a developer user, how can I ensure that content is accurate and up to date? Are alpha and beta features flagged? What happens when content (+ functionality) gets deprecated or changed in a major way? - - Who reviews documentation PRs? +- **Information Architecture:** Project Tremor's documentation makes a number of + individually small IA choices that culminate in a confusing experience for the + user. + + - The [Getting Started](https://www.tremor.rs/getting-started/) section covers + a number of seemingly random topics, with some appearing to be focused on + selling the project to new users (i.e. + [Good User Experience](https://www.tremor.rs/getting-started/tooling/)), + more traditional "getting started" content + ([Quick Install](https://www.tremor.rs/getting-started/install/)), and + high-level conceptual documentation + ([Understanding Data](https://www.tremor.rs/getting-started/codecs/)). + - Tremor has ample high-level conceptual overview information, but it's + somewhat scattered. + - The + [Architecture Overview - Goodness of fit](https://docs.tremor.rs/overview/) + section is probably the best overview for brand new users available, + however the rest of the page gets very detailed very quickly, and feels + like a collection of semi-random topics that someone felt the need to + write down, with no real direction. This page probably needs to be broken + up into many pages within a section, with some of the more esoteric topics + currently under "Getting Started" included. + - Low-level task content often gets buried in + [Recipes](https://docs.tremor.rs/tremor-query/recipes/), generically + titled + [Walkthrough](https://docs.tremor.rs/operations/configuration-walkthrough/) + pages, and the extremely helpful but poorly named + [Workshops](https://docs.tremor.rs/workshop/examples/00_passthrough/) + section. This makes it hard for a user with a specific query ("How do I + do....") to know, at a glance, if the documentation contains the answer to + their question or not. + - [The Configuration walkthrough](https://docs.tremor.rs/operations/configuration-walkthrough/) + was the single most useful page in terms of understanding the overall + 'picture' of what Tremor is and how a developer needs to move through the + documentation. But it's buried in the Configuration section, and I + wouldn't think to look there until I was much further in the process. + - Given how valuable the + [Workshops](https://docs.tremor.rs/workshop/examples/00_passthrough/) + section is, it needs a better name. "Recipes", "Tutorials", "How to" would + all be clearer. + - Some specific comments about the Tremor Query and Script sections: + - The [Tremor Query Overview](https://docs.tremor.rs/tremor-query/) and + [Tremor Script Overview](https://docs.tremor.rs/tremor-script/) would + benefit from splitting the "Language" topic and subtopics into their own + page in the section. + - As someone unfamiliar with the project, I'm not sure how + [Tremor Query](https://docs.tremor.rs/tremor-query/) and + [Tremor Script](https://docs.tremor.rs/tremor-script/) are different based + purely on their overviews. I'm also not sure if they work together or not, + or if I as a user need to use one language versus another. + - Given the complexity of Tremor's various query methods, I think focusing + on producing more [Recipes](https://docs.tremor.rs/tremor-script/recipes/) + would be a helpful next step for the team. + - [History](https://docs.tremor.rs/history/) probably doesn't belong as a + top-level section. + - [Development](https://docs.tremor.rs/development/) and + [Governance](https://docs.tremor.rs/CodeOfConduct/) are targeted at + contributor users rather than end users, and should be in a different + section of the site if possible. + +- **New user content:** Project Tremor has a Getting Started section but it's a + little disorganized as mentioned above. This makes it difficult for an actual + new user to understand. + + - [Starting Tremor for the first time](https://www.tremor.rs/getting-started/starting/) + is the best part of the getting started guide. However, it mentions that + there are "many ways" to install Tremor - it would be good to point users to + documentation on those other ways of installing. + - Is the + [Quick developer install](https://www.tremor.rs/getting-started/install/) + the "other methods"? There's no introduction to this page, so I can't + tell. + - [Talking to other systems](https://www.tremor.rs/getting-started/connectivity/) + is definitely a foundational concept for Tremor (as an events processing + system) but the style in which it's written isn't appropriate for a getting + started guide. This goes for + [Understanding Data](https://www.tremor.rs/getting-started/codecs/), + [Scripting](https://www.tremor.rs/getting-started/scripting/) and + [Specialize Tremor Pipelines](https://www.tremor.rs/getting-started/specialize/). + - These topics should be under Docs in their own section, perhaps titled + "Overview". + - Ensuring that all pages, like + [The Tremor CLI tool](https://docs.tremor.rs/operations/cli/), have + overviews goes a long way in ensuring the docs are user friendly for new + users. + - I like the [FAQ](https://www.tremor.rs/faq/) as new user content, but FAQs + often become a catch-all and get messy quickly. Proceed with caution. + +- **Content maintainability:** + - Docs are mostly separated into their own repository, + https://github.com/tremor-rs/tremor-www-docs, though as the maintainers note + there are many other repositories with docs available in them. These need to + be consolidated for easier maintenance. + - The + [scripts](https://github.com/tremor-rs/tremor-www-docs/tree/main/python_scripts) + which generate certain pieces of documentation introduce fragility into the + system: if the location of files, names of repos, etc. change then the + documentation pipeline breaks. This also makes it hard for non-"technical" + users to make changes to these pages, and to reorganize these pages if + needed. + - The automation benefits might be worth it however. + - Your + [release process](https://github.com/tremor-rs/tremor-www-docs/blob/main/RELEASE_PROCESS.md) + is documented, which is great to see! + - Your site is only partially searchable, with sections not within /docs + inaccessible by search. +- **Content creation processes:** There are no content creation processes + documented and no CONTRIBUTING.md file for the main docs repository. Some + things to think about: + - If I write documentation, who verifies that it's technically accurate? + - If I'm not a native English speaker, who can I ask for help with grammar and + language review? + - If I'm a trained technical writer and want to rearrange, create new, or + split existing topics, who do I tag in issues/on Slack for comment? + - As a developer user, how can I ensure that content is accurate and up to + date? Are alpha and beta features flagged? What happens when content (+ + functionality) gets deprecated or changed in a major way? + - Who reviews documentation PRs? **Recommendations** -- **Get specific about your Getting Started:** Getting Started Guides contain a very predictable set of content: - - In one paragraph or less, what is this piece of software - - What prerequisite software (i.e. Kubernetes) and knowledge (i.e., Go) do I need on my system to launch this? - - What special features does this piece of software have that other similar software might not have? - - What are the installation instructions? - - Is there a sample application I can set up and execute basic commands on? - -- **Reorganize the Operations section and retitle it "Using Tremor"**: Additionally, move some topics from the existing Getting Started section: - - [Configuring Tremor](https://docs.tremor.rs/operations/configuration-walkthrough/) - - [Walkthrough: Configure a Tremor Deployment](https://docs.tremor.rs/operations/configuration-walkthrough/) - - [Connectivity: Onramps and Offramps](https://www.tremor.rs/getting-started/connectivity/) - - Link to the [Onramps](https://docs.tremor.rs/artefacts/onramps/) and [Offramps](https://docs.tremor.rs/artefacts/offramps/) sections to point users to their next steps - - [Guaranteed Delivery](https://docs.tremor.rs/operations/gdcb/) (Note: this topic needs revision as it is not user friendly) - - [Linked Transports](https://docs.tremor.rs/operations/linked-transports/) - - Pipelines (Overview: what are pipelines? You can probably borrow content from the [Pipeline Model](https://docs.tremor.rs/overview/#pipeline-model) section of the architecture overview) - - Create a Tremor Pipeline - - [Specialize Tremor Pipelines](https://www.tremor.rs/getting-started/specialize/) - - [Processing Data](https://www.tremor.rs/getting-started/scripting/) - - Recipes/Examples - - [Monitoring](https://docs.tremor.rs/operations/monitoring/) - - [Tremor CLI Tool](https://docs.tremor.rs/operations/cli/) - - [IDE Add-ons](https://www.tremor.rs/getting-started/tooling/) - -- **Reorganize [Overview](https://docs.tremor.rs/overview/) with user-centeredness in mind**: I suggest creating a new section with the following content: - - The information on [The docs index](https://docs.tremor.rs/) as a page titled "Overview", with subpages: - - [Architecture Overview](https://docs.tremor.rs/overview/) (note: you could break out each of the "Model" sections into their own subpages) - - [History](https://docs.tremor.rs/history/), and I would consider titling this "Release log" or something similar - - [Understanding Data](https://www.tremor.rs/getting-started/codecs/) - -- **Audit for colloquial/casual language, abbreviations, and other "basic" English:** - - This recommendation has less to do with casual language or abbreviations being _bad_, and more to do with the perception of professionalism for the project. - - Review _all_ documentation for the following: - - Unnecessary abbreviations (for example [This page](https://docs.tremor.rs/operations/gdcb/)). - - Casual language or colloquialisms, for example: [A short "canned" synopsis](https://docs.tremor.rs/operations/gdcb/), referring to processes either as [painless](https://www.tremor.rs/getting-started/starting/#requirements) (on the same page: "let's be real"), etc. - - Spelling, consistent capitalization of titles, consistent verbiage in titles: - - In general when it comes to page titles, prefer either proper nouns (Good examples of this: [Lexical Preprocessor](https://docs.tremor.rs/tremor-script/pp/), [Linked Transports](https://docs.tremor.rs/operations/linked-transports/)), or verb-based phrases for tasks (For example, [Debugging with LLDB](https://docs.tremor.rs/development/debugging/)). +- **Get specific about your Getting Started:** Getting Started Guides contain a + very predictable set of content: + + - In one paragraph or less, what is this piece of software + - What prerequisite software (i.e. Kubernetes) and knowledge (i.e., Go) do I + need on my system to launch this? + - What special features does this piece of software have that other similar + software might not have? + - What are the installation instructions? + - Is there a sample application I can set up and execute basic commands on? + +- **Reorganize the Operations section and retitle it "Using Tremor"**: + Additionally, move some topics from the existing Getting Started section: + + - [Configuring Tremor](https://docs.tremor.rs/operations/configuration-walkthrough/) + - [Walkthrough: Configure a Tremor Deployment](https://docs.tremor.rs/operations/configuration-walkthrough/) + - [Connectivity: Onramps and Offramps](https://www.tremor.rs/getting-started/connectivity/) + - Link to the [Onramps](https://docs.tremor.rs/artefacts/onramps/) and + [Offramps](https://docs.tremor.rs/artefacts/offramps/) sections to point + users to their next steps + - [Guaranteed Delivery](https://docs.tremor.rs/operations/gdcb/) (Note: this + topic needs revision as it is not user friendly) + - [Linked Transports](https://docs.tremor.rs/operations/linked-transports/) + - Pipelines (Overview: what are pipelines? You can probably borrow content + from the [Pipeline Model](https://docs.tremor.rs/overview/#pipeline-model) + section of the architecture overview) + - Create a Tremor Pipeline + - [Specialize Tremor Pipelines](https://www.tremor.rs/getting-started/specialize/) + - [Processing Data](https://www.tremor.rs/getting-started/scripting/) + - Recipes/Examples + - [Monitoring](https://docs.tremor.rs/operations/monitoring/) + - [Tremor CLI Tool](https://docs.tremor.rs/operations/cli/) + - [IDE Add-ons](https://www.tremor.rs/getting-started/tooling/) + +- **Reorganize [Overview](https://docs.tremor.rs/overview/) with + user-centeredness in mind**: I suggest creating a new section with the + following content: + + - The information on [The docs index](https://docs.tremor.rs/) as a page + titled "Overview", with subpages: + - [Architecture Overview](https://docs.tremor.rs/overview/) (note: you could + break out each of the "Model" sections into their own subpages) + - [History](https://docs.tremor.rs/history/), and I would consider titling + this "Release log" or something similar + - [Understanding Data](https://www.tremor.rs/getting-started/codecs/) + +- **Audit for colloquial/casual language, abbreviations, and other "basic" + English:** + + - This recommendation has less to do with casual language or abbreviations + being _bad_, and more to do with the perception of professionalism for the + project. + - Review _all_ documentation for the following: + - Unnecessary abbreviations (for example + [This page](https://docs.tremor.rs/operations/gdcb/)). + - Casual language or colloquialisms, for example: + [A short "canned" synopsis](https://docs.tremor.rs/operations/gdcb/), + referring to processes either as + [painless](https://www.tremor.rs/getting-started/starting/#requirements) + (on the same page: "let's be real"), etc. + - Spelling, consistent capitalization of titles, consistent verbiage in + titles: + - In general when it comes to page titles, prefer either proper nouns + (Good examples of this: + [Lexical Preprocessor](https://docs.tremor.rs/tremor-script/pp/), + [Linked Transports](https://docs.tremor.rs/operations/linked-transports/)), + or verb-based phrases for tasks (For example, + [Debugging with LLDB](https://docs.tremor.rs/development/debugging/)). - **Rename Workshops section to "Recipes" or "Examples"** - **Create a CONTRIBUTING.md file for the docs repository** -## Contributor documentation - +## Contributor documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | | ✅ | -| Beginner friendly issue backlog | | | | | ✅ | -| “New contributor” getting started content | | | | ✅ | | -| Project governance documentation | | | | | | +| ----------------------------------------- | --- | --- | --- | --- | --- | +| Communication methods documented | | | | | ✅ | +| Beginner friendly issue backlog | | | | | ✅ | +| “New contributor” getting started content | | | | ✅ | | +| Project governance documentation | | | | | | + +Scale: -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** -- **Communication methods documented:** [Contributing](https://docs.tremor.rs/Contributing/) documents these, but it would be useful to pull these up to the Community page - -- **Beginner friendly issue backlog:** You document your [GitHub best practices](https://docs.tremor.rs/Contributing/#pull-requests) and [issues for new users are tagged](https://github.com/tremor-rs/tremor-www-docs/issues?q=is%3Aissue+is%3Aclosed). Great work! - - One thing to note is when tagging an issue [as a good first issue](https://github.com/tremor-rs/tremor-www-docs/issues/101), assume the reader knows nothing and must be hand-held through the entire process. [This issue](https://github.com/kubernetes/website/issues/28621) is a great example of the granularity needed by a first time contributor. - -- **New contributor getting started content:** The [Community](https://www.tremor.rs/community/) page exists but doesn't provide much guidance for new users. How do I get involved? When do community meetings happen? Where do I find the team on Discord or Slack? - - As mentioned above, [Development](https://docs.tremor.rs/development/) and [Governance](https://docs.tremor.rs/CodeOfConduct/) are targeted at contributor users and should be under the community section. - -- **Governance documentation:** Your [Project Governance](https://www.tremor.rs/governance/) is linked front and center, which I love! The only critique I have is that as a new user I am unlikely to click through to all of the links available. It would be lovely to distill these documents into something Tremor maintains at some point in the future. +- **Communication methods documented:** + [Contributing](https://docs.tremor.rs/Contributing/) documents these, but it + would be useful to pull these up to the Community page + +- **Beginner friendly issue backlog:** You document your + [GitHub best practices](https://docs.tremor.rs/Contributing/#pull-requests) + and + [issues for new users are tagged](https://github.com/tremor-rs/tremor-www-docs/issues?q=is%3Aissue+is%3Aclosed). + Great work! + + - One thing to note is when tagging an issue + [as a good first issue](https://github.com/tremor-rs/tremor-www-docs/issues/101), + assume the reader knows nothing and must be hand-held through the entire + process. [This issue](https://github.com/kubernetes/website/issues/28621) is + a great example of the granularity needed by a first time contributor. + +- **New contributor getting started content:** The + [Community](https://www.tremor.rs/community/) page exists but doesn't provide + much guidance for new users. How do I get involved? When do community meetings + happen? Where do I find the team on Discord or Slack? + + - As mentioned above, [Development](https://docs.tremor.rs/development/) and + [Governance](https://docs.tremor.rs/CodeOfConduct/) are targeted at + contributor users and should be under the community section. + +- **Governance documentation:** Your + [Project Governance](https://www.tremor.rs/governance/) is linked front and + center, which I love! The only critique I have is that as a new user I am + unlikely to click through to all of the links available. It would be lovely to + distill these documents into something Tremor maintains at some point in the + future. **Recommendations** -- **Turn the Community page into a subsection and house Governance and Development documentation under it:** - - Specifically, move [Development](https://docs.tremor.rs/development/) to /community/development - - Move [The entire governance section](https://docs.tremor.rs/Contributing/#pull-requests) as well - - Consider moving [RFCs](https://rfcs.tremor.rs/) under community as well +- **Turn the Community page into a subsection and house Governance and + Development documentation under it:** -- **Pull meeting and contact information out of contributing and onto the community page:** people cannot join a meeting or chat that they can't find a link to. + - Specifically, move [Development](https://docs.tremor.rs/development/) to + /community/development + - Move + [The entire governance section](https://docs.tremor.rs/Contributing/#pull-requests) + as well + - Consider moving [RFCs](https://rfcs.tremor.rs/) under community as well +- **Pull meeting and contact information out of contributing and onto the + community page:** people cannot join a meeting or chat that they can't find a + link to. ## Website - | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Branding and design | | | | ✅ | | -| Case studies/social proof | ✅ | | | | | -| Maintenance planning | | ✅ | | | | +| ------------------------- | --- | --- | --- | --- | --- | +| Branding and design | | | | ✅ | | +| Case studies/social proof | ✅ | | | | | +| Maintenance planning | | ✅ | | | | + +Scale: -Scale: - 1 = (Is not present or requires significant work) - 3 = (Is present, but needs work) - 5 = (Is executed extremely well or no improvement required) @@ -174,55 +319,80 @@ Scale: **Comments** - **Branding and design:** - - On the whole, the Tremor docs site looks professional, if a little plain. - - Because of the way the site deploys (from different repositories via GitHub pages), navigation is disjointed: if you're in the RFCs, you don't have the full site's navigation available to you and clicking the logo takes you back to https://rfcs.tremor.rs, with similar behavior occurring in the docs. This is a bad user experience. - - Tremor could do a bit more selling on its homepage: - - What are the project's key features that make it different from other event processing systems? - - Are there any known use cases you can talk about or use the logos of? - - Have you given any talks on Tremor, or is there other (particularly video) content you can showcase about the project? - -- **Case studies/social proof**: None available. - - Case studies/talks/generally showing that other projects use Tremor is one of the most powerful ways to gain new users. People love real-world examples of a codebase in action. - - Because Tremor was developed by Wayfair, we suggest documenting Wayfair's use as a "use case" or case study, and then adding a section on the website which allows people to submit their own use cases! - -- **Maintenance planning:** In general, we recommend that projects keep their documentation all in one repository. Tremor's documentation currently deploys from https://github.com/tremor-rs/tremor-www-main, https://github.com/tremor-rs/tremor-rfcs, and https://github.com/tremor-rs/tremor-www-docs. - - It's confusing for contributors who don't know where to file issues, open pull requests, or whom to tag for reviews (and where). - - The easiest fix for this pain point is to deploy everything using and Hugo. - - In general, we prefer sites to deploy via Netlify. -**Recommendations** + - On the whole, the Tremor docs site looks professional, if a little plain. + - Because of the way the site deploys (from different repositories via GitHub + pages), navigation is disjointed: if you're in the RFCs, you don't have the + full site's navigation available to you and clicking the logo takes you back + to https://rfcs.tremor.rs, with similar behavior occurring in the docs. This + is a bad user experience. + - Tremor could do a bit more selling on its homepage: + - What are the project's key features that make it different from other + event processing systems? + - Are there any known use cases you can talk about or use the logos of? + - Have you given any talks on Tremor, or is there other (particularly video) + content you can showcase about the project? + +- **Case studies/social proof**: None available. + + - Case studies/talks/generally showing that other projects use Tremor is one + of the most powerful ways to gain new users. People love real-world examples + of a codebase in action. + - Because Tremor was developed by Wayfair, we suggest documenting Wayfair's + use as a "use case" or case study, and then adding a section on the website + which allows people to submit their own use cases! + +- **Maintenance planning:** In general, we recommend that projects keep their + documentation all in one repository. Tremor's documentation currently deploys + from https://github.com/tremor-rs/tremor-www-main, + https://github.com/tremor-rs/tremor-rfcs, and + https://github.com/tremor-rs/tremor-www-docs. + - It's confusing for contributors who don't know where to file issues, open + pull requests, or whom to tag for reviews (and where). + - The easiest fix for this pain point is to deploy everything using and Hugo. + - In general, we prefer sites to deploy via Netlify. -- Develop a case study or other content around Wayfair's use of Tremor, to give users a tangible example of what they can do with the project. +**Recommendations** -- Fix navigation and improve site maintainability by putting all your documentation in one repository. +- Develop a case study or other content around Wayfair's use of Tremor, to give + users a tangible example of what they can do with the project. +- Fix navigation and improve site maintainability by putting all your + documentation in one repository. ## Recommendations -**Reorganize your documentation's information architecture:** In addition to the suggestions above, I recommend an overall reorganization of the documentation, along the lines of: +**Reorganize your documentation's information architecture:** In addition to the +suggestions above, I recommend an overall reorganization of the documentation, +along the lines of: - Docs - - Overview (renamed from Architecture Overview) - - Using Tremor - - subpages as described previously - - Artifacts - - Tremor Query - - Tremor Script - - Examples (renamed from Workshops) - - API Reference - - Glossary - - FAQ (moved from top level navigation) - -**Reorganize the top-level navigation of the site:** once again, as mentioned previously: - -- Getting Started + - Overview (renamed from Architecture Overview) + - Using Tremor + - subpages as described previously + - Artifacts + - Tremor Query + - Tremor Script + - Examples (renamed from Workshops) + - API Reference + - Glossary + - FAQ (moved from top level navigation) + +**Reorganize the top-level navigation of the site:** once again, as mentioned +previously: + +- Getting Started - Docs - - subsections as described above -- Community - - RFCs - - Contributing (moved from Docs section) - - Governance (moved from Docs section) + - subsections as described above +- Community + - RFCs + - Contributing (moved from Docs section) + - Governance (moved from Docs section) - Community Chat -- Blog +- Blog -**Consolidate documentation into one repository, and document contributing guidelines for users:** I recommend collapsing everything into https://github.com/tremor-rs/tremor-www-main, barring any technical difficulties doing so, and switching deploys over to Netlify to access Deploy previews and other useful features. +**Consolidate documentation into one repository, and document contributing +guidelines for users:** I recommend collapsing everything into +https://github.com/tremor-rs/tremor-www-main, barring any technical difficulties +doing so, and switching deploys over to Netlify to access Deploy previews and +other useful features. diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md index 015bcd7..c24b545 100644 --- a/analyses/0005-fluxcd.md +++ b/analyses/0005-fluxcd.md @@ -1,11 +1,12 @@ # Assessment template -Prepared by: Celeste Horgan ([@celestehorgan](https://github.com/cncf/techdocs))
-Date: 2021-11-30 +Prepared by: Celeste Horgan +([@celestehorgan](https://github.com/cncf/techdocs))
Date: 2021-11-30 ## Introduction -This document assesses the quality and completeness of a project's documentation and website (if present). +This document assesses the quality and completeness of a project's documentation +and website (if present). This document: @@ -14,162 +15,244 @@ This document: - Provides examples of great documentation as reference - Identifies key improvements with the largest return on investment - ## How this document works The assessment is divided into three sections: -- **Project documentation:** for end users of the project; aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project +- **Project documentation:** for end users of the project; aimed at people who + intend to use it +- **Contributor documentation:** for new and existing contributors to the + project - **Website:** branding, website structure, and maintainability Each section rates content based on different [criteria](criteria.md). - ## Project documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Information architecture | | | | ✅ | | -| New user content | | | | | ✅ | -| Content maintainability | | | | | ✅ | -| Content creation processes | | | | | ✅ | +| -------------------------- | --- | --- | --- | --- | --- | +| Information architecture | | | | ✅ | | +| New user content | | | | | ✅ | +| Content maintainability | | | | | ✅ | +| Content creation processes | | | | | ✅ | 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 -**Information architecture**: - -- Flux's documentation is well organized, but there are improvements we could make: - - Between the [Guides](https://fluxcd.io/docs/guides/) and [Use cases](https://fluxcd.io/docs/use-cases/) overlap a bit. The topics in these two sections are around installing and using Flux with a variety of different technologies. The names of both are somewhat vague which causes a lack of clarity for the reader: they need to click in to understand what each section is about, and even after doing so it isn't entirely clear. - - The [Migration](https://fluxcd.io/docs/migration/) section isn't more important than [Toolkit components](https://fluxcd.io/docs/components/), [Toolkit dev guides](https://fluxcd.io/docs/gitops-toolkit/), or the [Flux CLI reference](https://fluxcd.io/docs/cmd/). Placing it above these in the information architecture doesn't make sense. - -**New user content**: - -- Flux has a thorough [Getting Started](https://fluxcd.io/docs/get-started/) page, complimented by a multi-CLI [Installation guide](https://fluxcd.io/docs/installation/) and an informative [Docs root](https://fluxcd.io/docs/concepts/). Together these three pages work well to introduce new users to Flux. No real improvements needed! - -**Content maintainability & site mechanics**: - -- Documentation lives in the `flux/website` repository and uses Hugo+Docsy, which is our recommended stack! Full marks in this regard. There are two areas of potential concern: - The [Toolkit Components](https://fluxcd.io/docs/components/) section: - - The [documentation](https://github.com/fluxcd/website/tree/main/external-sources) is a touch opaque - - The [resulting documentation](https://fluxcd.io/docs/components/helm/helmreleases/) is not user friendly: it is difficult to read and difficult to understand. A useful statistic to keep in mind is that while 50% of developers learn best by looking at code and "hacking", the other 50% of developers want to understand high-level concepts better before beginning code: providing a bit more explanation up front, particularly around the object's required fields and what the expected values are. An example would be helpful for this audience. - - Items under the **Project** top level navigation section. At a glance I couldn't figure out how these were being pulled in via (I assume) the [Community repository](https://github.com/fluxcd/community), meaning they suffer either from a lack of documentation or unclear automation. - -- Documentation versioning: Flux's documentation is not versioned but the tool itself has been versioned. - - This leaves existing users of v1 who haven't upgraded in a difficult position: if they need to troubleshoot an issue, they can't access v1 documentation. - - Flux has a large enough adopter community that back version support is something that needs to be managed carefully. If Flux versions the tool again, in such a way that introduces breaking changes, I strongly recommend reaching out to the TechDocs team for assistance in versioning your documentation. If you don't plan to introduce any breaking changes any time soon, I wouldn't worry about versioning for now :) - - The site is searchable, but as mentioned previously: the user only knows they're dealing with versioned content when they dive into the migration guide. - -**Content creation processes**: +**Information architecture**: -- The [Contributing Guide](https://fluxcd.io/docs/contributing/docs/) contains really thorough documentation on contributing to both docs and the project itself! +- Flux's documentation is well organized, but there are improvements we could + make: + - Between the [Guides](https://fluxcd.io/docs/guides/) and + [Use cases](https://fluxcd.io/docs/use-cases/) overlap a bit. The topics in + these two sections are around installing and using Flux with a variety of + different technologies. The names of both are somewhat vague which causes a + lack of clarity for the reader: they need to click in to understand what + each section is about, and even after doing so it isn't entirely clear. + - The [Migration](https://fluxcd.io/docs/migration/) section isn't more + important than [Toolkit components](https://fluxcd.io/docs/components/), + [Toolkit dev guides](https://fluxcd.io/docs/gitops-toolkit/), or the + [Flux CLI reference](https://fluxcd.io/docs/cmd/). Placing it above these in + the information architecture doesn't make sense. + +**New user content**: + +- Flux has a thorough [Getting Started](https://fluxcd.io/docs/get-started/) + page, complimented by a multi-CLI + [Installation guide](https://fluxcd.io/docs/installation/) and an informative + [Docs root](https://fluxcd.io/docs/concepts/). Together these three pages work + well to introduce new users to Flux. No real improvements needed! + +**Content maintainability & site mechanics**: + +- Documentation lives in the `flux/website` repository and uses Hugo+Docsy, + which is our recommended stack! Full marks in this regard. There are two areas + of potential concern: The + [Toolkit Components](https://fluxcd.io/docs/components/) section: - The + [documentation](https://github.com/fluxcd/website/tree/main/external-sources) + is a touch opaque - The + [resulting documentation](https://fluxcd.io/docs/components/helm/helmreleases/) + is not user friendly: it is difficult to read and difficult to understand. A + useful statistic to keep in mind is that while 50% of developers learn best by + looking at code and "hacking", the other 50% of developers want to understand + high-level concepts better before beginning code: providing a bit more + explanation up front, particularly around the object's required fields and + what the expected values are. An example would be helpful for this audience. + + - Items under the **Project** top level navigation section. At a glance I + couldn't figure out how these were being pulled in via (I assume) the + [Community repository](https://github.com/fluxcd/community), meaning they + suffer either from a lack of documentation or unclear automation. + +- Documentation versioning: Flux's documentation is not versioned but the tool + itself has been versioned. + - This leaves existing users of v1 who haven't upgraded in a difficult + position: if they need to troubleshoot an issue, they can't access v1 + documentation. + - Flux has a large enough adopter community that back version support is + something that needs to be managed carefully. If Flux versions the tool + again, in such a way that introduces breaking changes, I strongly recommend + reaching out to the TechDocs team for assistance in versioning your + documentation. If you don't plan to introduce any breaking changes any time + soon, I wouldn't worry about versioning for now :) + - The site is searchable, but as mentioned previously: the user only knows + they're dealing with versioned content when they dive into the migration + guide. + +**Content creation processes**: + +- The [Contributing Guide](https://fluxcd.io/docs/contributing/docs/) contains + really thorough documentation on contributing to both docs and the project + itself! + +- Maintainers are + [clearly documented](https://github.com/fluxcd/website/blob/main/MAINTAINERS) + as well as where to find them. -- Maintainers are [clearly documented](https://github.com/fluxcd/website/blob/main/MAINTAINERS) as well as where to find them. - ### Recommendations **Information architecture**: -- Reorganize the [Guides](https://fluxcd.io/docs/guides/) and [Use cases](https://fluxcd.io/docs/use-cases/): - - Docs root - - ... - - Installation - - Integrating Flux - - Azure - - OpenShift - - Helm - - Jenkins - - Prometheus - - Flux Notifications - - Automation & GitOps - - Ways of structuring your repositories - - Setup webhook receivers - - Sealed Secrets - - Manage Kubernetes secrets with Mozilla SOPS - - Automate image updates to Git - - How to make sortable image tags to use with automation - - GitHub Actions Manifest Generation - - GitHub Actions Auto Pull Request - -- Move the [Migration Guide](https://fluxcd.io/docs/guides/) to either a subsection of [Get Started](https://fluxcd.io/docs/get-started/) or a subsection of [Installation](https://fluxcd.io/docs/installation/) - - Consider renaming "Migration guide" to "Migrate from Flux v1" for clarity - -**Content maintenance**: - -- If you decide to version the Flux tool again (with the same level of breaking changes that v1 to v2 introduced), consider versioning your documentation. - -- Write down what areas are automatically pulled in from other repositories, what comes in from command line, etc. - -- [This file](https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh) is _very_ fragile, as it points to specific files at their `https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh` and seems to have the potential to make the site build succeed but with unpredictable results. - - Consider implementing [Hugo Modules](https://gohugo.io/hugo-modules/) to bring things in in a less fragile manner. - - Alternately, consider reducing the files brought in to the bare minimum and writing a set of unit tests for the website repository, ensuring that the build fails when files are moved or renamed. - -**Content creation processes**: - -- Put [this information](https://github.com/fluxcd/website/blob/main/content/en/docs/contributing/docs/some-background.md#running-the-site-locally) directly in the README.md of the website repository, because people are lazy. Kudos on trying to keep everything in one place, however! - +- Reorganize the [Guides](https://fluxcd.io/docs/guides/) and + [Use cases](https://fluxcd.io/docs/use-cases/): + - Docs root + - ... + - Installation + - Integrating Flux + - Azure + - OpenShift + - Helm + - Jenkins + - Prometheus + - Flux Notifications + - Automation & GitOps + - Ways of structuring your repositories + - Setup webhook receivers + - Sealed Secrets + - Manage Kubernetes secrets with Mozilla SOPS + - Automate image updates to Git + - How to make sortable image tags to use with automation + - GitHub Actions Manifest Generation + - GitHub Actions Auto Pull Request +- Move the [Migration Guide](https://fluxcd.io/docs/guides/) to either a + subsection of [Get Started](https://fluxcd.io/docs/get-started/) or a + subsection of [Installation](https://fluxcd.io/docs/installation/) + - Consider renaming "Migration guide" to "Migrate from Flux v1" for clarity + +**Content maintenance**: + +- If you decide to version the Flux tool again (with the same level of breaking + changes that v1 to v2 introduced), consider versioning your documentation. + +- Write down what areas are automatically pulled in from other repositories, + what comes in from command line, etc. + +- [This file](https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh) + is _very_ fragile, as it points to specific files at their + `https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh` and + seems to have the potential to make the site build succeed but with + unpredictable results. + - Consider implementing [Hugo Modules](https://gohugo.io/hugo-modules/) to + bring things in in a less fragile manner. + - Alternately, consider reducing the files brought in to the bare minimum and + writing a set of unit tests for the website repository, ensuring that the + build fails when files are moved or renamed. + +**Content creation processes**: + +- Put + [this information](https://github.com/fluxcd/website/blob/main/content/en/docs/contributing/docs/some-background.md#running-the-site-locally) + directly in the README.md of the website repository, because people are lazy. + Kudos on trying to keep everything in one place, however! ## Contributor documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | | ✅ | -| Beginner friendly issue backlog | | | | | ✅ | -| “New contributor” getting started content | | | | ✅ | | -| Project governance documentation | | | | | ✅ | +| ----------------------------------------- | --- | --- | --- | --- | --- | +| Communication methods documented | | | | | ✅ | +| Beginner friendly issue backlog | | | | | ✅ | +| “New contributor” getting started content | | | | ✅ | | +| Project governance documentation | | | | | ✅ | 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 -- **Communication methods** are [clearly documented](https://fluxcd.io/docs/contributing/flux/#communications), as well as how (and where) to get calendar invites for meetings -- The **issue backlog** is [very beginner friendly](https://github.com/fluxcd/flux2/issues) and well groomed -- **New contributor getting started content** could use a little bit of work: simply put, as a reviewer I wonder how you could reconcile the [Flux Contributor Guide](https://fluxcd.io/docs/contributing/) and it's high visibility via the project website and the wealth of information in the [Community repository](https://github.com/fluxcd/community). -- Project governance is [clearly documented](https://fluxcd.io/governance/). The community repository also includes information on [Oversight](https://github.com/fluxcd/community/blob/main/OVERSIGHT.md), [Community roles](https://github.com/fluxcd/community/blob/main/community-roles.md), and more. - +- **Communication methods** are + [clearly documented](https://fluxcd.io/docs/contributing/flux/#communications), + as well as how (and where) to get calendar invites for meetings +- The **issue backlog** is + [very beginner friendly](https://github.com/fluxcd/flux2/issues) and well + groomed +- **New contributor getting started content** could use a little bit of work: + simply put, as a reviewer I wonder how you could reconcile the + [Flux Contributor Guide](https://fluxcd.io/docs/contributing/) and it's high + visibility via the project website and the wealth of information in the + [Community repository](https://github.com/fluxcd/community). +- Project governance is [clearly documented](https://fluxcd.io/governance/). The + community repository also includes information on + [Oversight](https://github.com/fluxcd/community/blob/main/OVERSIGHT.md), + [Community roles](https://github.com/fluxcd/community/blob/main/community-roles.md), + and more. ### Recommendations -- Because the community repository is almost - but not entirely - mirrored on the website, it's hard to understand what the main entry point is for new contributors. It's also difficult to understand whether content should be in the Contributor Guide on the website versus the community repository. The project team should clearly define the roles of both of these homes for contributor information and reorganize appropriately. - +- Because the community repository is almost - but not entirely - mirrored on + the website, it's hard to understand what the main entry point is for new + contributors. It's also difficult to understand whether content should be in + the Contributor Guide on the website versus the community repository. The + project team should clearly define the roles of both of these homes for + contributor information and reorganize appropriately. ## Website | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Single-source for all files | | | ✅ | | | -| Meets min website req. (for maturity level) | | | | ✅ | | -| Branding and design | | | | | ✅ | -| Case studies/social proof | | | | ✅ | | -| Maintenance planning | | | | | ✅ | -| A11y plan & implementation | | | | ✅ | | -| Mobile-first plan & impl. | | | | | ✅ | -| HTTPS access & HTTP redirect | | | | | ✅ | +| ------------------------------------------- | --- | --- | --- | --- | --- | +| Single-source for all files | | | ✅ | | | +| Meets min website req. (for maturity level) | | | | ✅ | | +| Branding and design | | | | | ✅ | +| Case studies/social proof | | | | ✅ | | +| Maintenance planning | | | | | ✅ | +| A11y plan & implementation | | | | ✅ | | +| Mobile-first plan & impl. | | | | | ✅ | +| HTTPS access & HTTP redirect | | | | | ✅ | 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 -- **Single source for all files**: While all files are single sourced (that is, files are not duplicated), [the build process which governs](https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh) pulling in and building out some webpages is very fragile. In my career as a technical writer I have seen similar setups fail due to catastrophic fragility, particularly once the original code owners leave the organization. +- **Single source for all files**: While all files are single sourced (that is, + files are not duplicated), + [the build process which governs](https://github.com/fluxcd/website/blob/main/hack/import-flux2-assets.sh) + pulling in and building out some webpages is very fragile. In my career as a + technical writer I have seen similar setups fail due to catastrophic + fragility, particularly once the original code owners leave the organization. -- Flux meets and exceeds the [website requirements](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md#minimal-website-requirements) for its maturity level, save for the single sourcing requirement as noted above. +- Flux meets and exceeds the + [website requirements](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md#minimal-website-requirements) + for its maturity level, save for the single sourcing requirement as noted + above. - The website is mobile friendly -- The website meets the basic a11y requirements (high contrast text), but could improve on images +- The website meets the basic a11y requirements (high contrast text), but could + improve on images -- Branding is consistently applied throughout the site, despite using Docsy+Hugo. The site feels professional and well maintained. +- Branding is consistently applied throughout the site, despite using + Docsy+Hugo. The site feels professional and well maintained. ### Recommendations @@ -178,6 +261,9 @@ Scale: ## Final Recommendations 1. Reorganize the guides [as mentioned above](#project-documentation) -2. Work with the techdocs team on an in-depth edit of your content: most of the content is excellent, and simply needs a proofreading pass from an experienced writer. -3. Rework the [Toolkit Components](https://fluxcd.io/docs/components/) section to improve the fragility of generating these files, as well as the documentation user experience for readers. - +2. Work with the techdocs team on an in-depth edit of your content: most of the + content is excellent, and simply needs a proofreading pass from an + experienced writer. +3. Rework the [Toolkit Components](https://fluxcd.io/docs/components/) section + to improve the fragility of generating these files, as well as the + documentation user experience for readers. diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md index 25f3180..ec69e59 100644 --- a/analyses/0006-gateway-api.md +++ b/analyses/0006-gateway-api.md @@ -1,11 +1,13 @@ # Assessment: Project Kubernetes Gateway API -Prepared by: Meha Bhalodiya ([@mehabhalodiya](https://github.com/mehabhalodiya))
-Date: 2021-03-03 +Prepared by: Meha Bhalodiya +([@mehabhalodiya](https://github.com/mehabhalodiya))
Date: 2021-03-03 ## Introduction -This document assesses the quality and completeness of the Kubernetes Gateway API [project's](https://github.com/kubernetes-sigs/gateway-api) documentation and [website](https://gateway-api.sigs.k8s.io/). +This document assesses the quality and completeness of the Kubernetes Gateway +API [project's](https://github.com/kubernetes-sigs/gateway-api) documentation +and [website](https://gateway-api.sigs.k8s.io/). This document: @@ -14,44 +16,53 @@ This document: - Provide examples of great documentation as a reference - Identifies key improvements with the largest return on investment - ## How this document works The assessment is divided into three sections: -- **Project documentation:** for end-users of the project; aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project +- **Project documentation:** for end-users of the project; aimed at people who + intend to use it +- **Contributor documentation:** for new and existing contributors to the + project - **Website:** branding, website structure, and maintainability Each section rates content based on different [criteria](criteria.md). - ## Project documentation -| Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Information architecture | | ✅ | | | | -| New user content | | | ✅ | | | -| Content maintainability & site mechanics | | | | ✅ | | -| Content creation processes | | | | ✅ | | - +| Criteria | 1 | 2 | 3 | 4 | 5 | +| ---------------------------------------- | --- | --- | --- | --- | --- | +| Information architecture | | ✅ | | | | +| New user content | | | ✅ | | | +| Content maintainability & site mechanics | | | | ✅ | | +| Content creation processes | | | | ✅ | | 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 **Information architecture**: -The brief information is mentioned on [the Introductory](https://gateway-api.sigs.k8s.io/) page, but we need to organize it well. Also, [API conventions](https://gateway-api.sigs.k8s.io/concepts/guidelines/?h=api+conve#api-conventions) are mentioned in brief, great work! +The brief information is mentioned on +[the Introductory](https://gateway-api.sigs.k8s.io/) page, but we need to +organize it well. Also, +[API conventions](https://gateway-api.sigs.k8s.io/concepts/guidelines/?h=api+conve#api-conventions) +are mentioned in brief, great work! -**New user content**: +**New user content**: + +We have a great, clearly labelled +[Getting Started](https://gateway-api.sigs.k8s.io/v1alpha2/guides/getting-started/) +page, which is awesome! However, the getting started guide is fairly high level +and doesn't answer some of the following questions: + +- What are the prerequisites that need to be installed beforehand? Or What else + do I need aside from Gateway Controller? -We have a great, clearly labelled [Getting Started](https://gateway-api.sigs.k8s.io/v1alpha2/guides/getting-started/) page, which is awesome! However, the getting started guide is fairly high level and doesn't answer some of the following questions: -- What are the prerequisites that need to be installed beforehand? Or What else do I need aside from Gateway Controller? * Where to go and what to do after reading the “Getting Started” guide? **Content maintainability**: @@ -60,114 +71,148 @@ Our documentation is searchable, which is great! **Content creation processes**: -The [Contributing Guide](https://gateway-api.sigs.k8s.io/contributing/devguide/) contains really thorough documentation on contributing to both docs and the project itself! In the [README](https://github.com/kubernetes-sigs/gateway-api#readme), maintainers are not [clearly documented](https://github.com/kubernetes-sigs/gateway-api/blob/master/OWNERS_ALIASES) as well as where to find them. - +The [Contributing Guide](https://gateway-api.sigs.k8s.io/contributing/devguide/) +contains really thorough documentation on contributing to both docs and the +project itself! In the +[README](https://github.com/kubernetes-sigs/gateway-api#readme), maintainers are +not +[clearly documented](https://github.com/kubernetes-sigs/gateway-api/blob/master/OWNERS_ALIASES) +as well as where to find them. ### Recommendations **Information architecture:** -- The main task with information architecture is conceptualization and development as the documents are currently in different places. The following areas would establish a foundation: +- The main task with information architecture is conceptualization and + development as the documents are currently in different places. The following + areas would establish a foundation: - * Introduction - * Quick Start - * Concepts - * Tutorials - * Reference - * Contribute + - Introduction + - Quick Start + - Concepts + - Tutorials + - Reference + - Contribute -- **Prepared a miro board: [https://miro.com/app/board/uXjVO_1cS9k=/](https://miro.com/app/board/uXjVO_1cS9k=/)** - - ![information_architecture](/images/gapi_info_arch.png) +- **Prepared a miro board: + [https://miro.com/app/board/uXjVO_1cS9k=/](https://miro.com/app/board/uXjVO_1cS9k=/)** + ![information_architecture](/images/gapi_info_arch.png) - There are improvements we could make: - * With the collection of guided, step-by-step instructions (tasks, hands-on tutorials) documented for features, it would be easy to learn and explore this project. - * [Gateway API Concepts](https://gateway-api.sigs.k8s.io/#gateway-api-concepts) should go somewhere inside the Concepts section of the Overview page. + - With the collection of guided, step-by-step instructions (tasks, hands-on + tutorials) documented for features, it would be easy to learn and explore + this project. + - [Gateway API Concepts](https://gateway-api.sigs.k8s.io/#gateway-api-concepts) + should go somewhere inside the Concepts section of the Overview page. **Content maintainability**: -- We need to add some information regarding “**How do we update the code for new versions?**”, and “**How do we update the documentation when a new version is released?**”. +- We need to add some information regarding “**How do we update the code for new + versions?**”, and “**How do we update the documentation when a new version is + released?**”. - In short, we need to write up the process for versioning the documentation. \ -Reference: [https://cluster-api.sigs.k8s.io/contributing#versioning](https://cluster-api.sigs.k8s.io/contributing#versioning) - + Reference: [https://cluster-api.sigs.k8s.io/contributing#versioning](https://cluster-api.sigs.k8s.io/contributing#versioning) -**Content creation processes**: - -We can put up a MAINTAINERS.md file for tagging & contact purposes in the project repo. -We may want to look into how to get the API stuff [here](https://clomonitor.io) to track some of the docs requirements, like a MAINTAINERS file. +**Content creation processes**: +We can put up a MAINTAINERS.md file for tagging & contact purposes in the +project repo. We may want to look into how to get the API stuff +[here](https://clomonitor.io) to track some of the docs requirements, like a +MAINTAINERS file. ## Contributor documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | | ✅ | -| Beginner friendly issue backlog | | ✅ | | | | -| “New contributor” getting started content | | | ✅ | | | -| Project governance documentation | | | | | ✅ | +| ----------------------------------------- | --- | --- | --- | --- | --- | +| Communication methods documented | | | | | ✅ | +| Beginner friendly issue backlog | | ✅ | | | | +| “New contributor” getting started content | | | ✅ | | | +| Project governance documentation | | | | | ✅ | 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 **Communication methods documented**: -Communication [methods](https://gateway-api.sigs.k8s.io/contributing/community/#communications) are clearly documented. It contains everything starting from community groups, slack, mailing lists and forums, calendars and meetings, social media and blogs to community resources. +Communication +[methods](https://gateway-api.sigs.k8s.io/contributing/community/#communications) +are clearly documented. It contains everything starting from community groups, +slack, mailing lists and forums, calendars and meetings, social media and blogs +to community resources. **Beginner-friendly issue backlog**: -While there is an issue backlog, there aren't any consistent workaround issues with a [good first issue](https://github.com/kubernetes-sigs/gateway-api/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) label. To invite new contributors, consider filing issues that are easy to remedy, label them accordingly (try keeping up-to-date, seems many are [frozen](https://github.com/kubernetes-sigs/gateway-api/issues?q=is%3Aopen+is%3Aissue+label%3Alifecycle%2Ffrozen)), post them on Slack channels, and be available to help contributors through the process. +While there is an issue backlog, there aren't any consistent workaround issues +with a +[good first issue](https://github.com/kubernetes-sigs/gateway-api/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) +label. To invite new contributors, consider filing issues that are easy to +remedy, label them accordingly (try keeping up-to-date, seems many are +[frozen](https://github.com/kubernetes-sigs/gateway-api/issues?q=is%3Aopen+is%3Aissue+label%3Alifecycle%2Ffrozen)), +post them on Slack channels, and be available to help contributors through the +process. **"New contributor" getting started content**: -There is a brief mention about the ‘Getting Started’ process in the [CONTRIBUTING.md](https://github.com/kubernetes-sigs/gateway-api/blob/master/CONTRIBUTING.md), however giving more detail would be better. +There is a brief mention about the ‘Getting Started’ process in the +[CONTRIBUTING.md](https://github.com/kubernetes-sigs/gateway-api/blob/master/CONTRIBUTING.md), +however giving more detail would be better. **Project governance documentation**: -Project [governance](https://github.com/kubernetes/community/blob/master/governance.md) is clearly documented in the community repo. - +Project +[governance](https://github.com/kubernetes/community/blob/master/governance.md) +is clearly documented in the community repo. ### Recommendations **Beginner-friendly issue backlog**: -Please ensure that the issue contains sufficient context and information about what exactly needs to be done so that a new contributor can pick it up with almost 0 barrier to entry. The guidelines for good-first-issues can be found [here](https://github.com/kubernetes/community/blob/master/contributors/guide/help-wanted.md#good-first-issue). +Please ensure that the issue contains sufficient context and information about +what exactly needs to be done so that a new contributor can pick it up with +almost 0 barrier to entry. The guidelines for good-first-issues can be found +[here](https://github.com/kubernetes/community/blob/master/contributors/guide/help-wanted.md#good-first-issue). **“New contributor” getting started content**: -We need to document other sections in [CONTRIBUTING.md](https://github.com/kubernetes-sigs/gateway-api/blob/master/CONTRIBUTING.md) for new contributors and make the process as smooth as possible. Also, some work around the [community](https://gateway-api.sigs.k8s.io/contributing/community/) page is needed. - +We need to document other sections in +[CONTRIBUTING.md](https://github.com/kubernetes-sigs/gateway-api/blob/master/CONTRIBUTING.md) +for new contributors and make the process as smooth as possible. Also, some work +around the [community](https://gateway-api.sigs.k8s.io/contributing/community/) +page is needed. ## Website | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Single-source for all files | | | ✅ | | | -| Meets min website req. (for maturity level) | | | | | ✅ | -| Branding and design | | | | ✅ | | -| Case studies/social proof | | | ✅ | | | -| Maintenance planning | | | ✅ | | | -| A11y plan & implementation | | | | | ✅ | -| Mobile-first plan & impl. | | | | | ✅ | -| HTTPS access & HTTP redirect | | | | | ✅ | +| ------------------------------------------- | --- | --- | --- | --- | --- | +| Single-source for all files | | | ✅ | | | +| Meets min website req. (for maturity level) | | | | | ✅ | +| Branding and design | | | | ✅ | | +| Case studies/social proof | | | ✅ | | | +| Maintenance planning | | | ✅ | | | +| A11y plan & implementation | | | | | ✅ | +| Mobile-first plan & impl. | | | | | ✅ | +| HTTPS access & HTTP redirect | | | | | ✅ | 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 **Single-source for all files**: -While all files are single-sourced (that is, files are not duplicated), [the build process which governs](https://github.com/kubernetes-sigs/gateway-api/blob/master/hack/make-docs.sh) pulling in and building out some webpages is very fragile. +While all files are single-sourced (that is, files are not duplicated), +[the build process which governs](https://github.com/kubernetes-sigs/gateway-api/blob/master/hack/make-docs.sh) +pulling in and building out some webpages is very fragile. **Meets min website req. (for maturity level)**: @@ -175,52 +220,72 @@ Project meets website requirements for its maturity level. **Branding and design**: -Branding is consistently applied throughout the site. Also, the website’s typography is clean and well-suited for reading. Thus, the site looks professional! No major improvements are needed. +Branding is consistently applied throughout the site. Also, the website’s +typography is clean and well-suited for reading. Thus, the site looks +professional! No major improvements are needed. **Case studies/social proof**: -[Implementations](https://gateway-api.sigs.k8s.io/implementations/) are well-written. The project should be more active in producing blog posts. +[Implementations](https://gateway-api.sigs.k8s.io/implementations/) are +well-written. The project should be more active in producing blog posts. **Maintenance planning**: -Having a docs+code monorepo is risky in the long term, as it couples all docs built with code builds and vice versa. If docs CI fails because Netlify is temporarily down, for example, this means that all your code builds can potentially fail as well. Coupling docs in a repository with code can also make a code repo's size expand exponentially, especially as projects pick up steam, write more blog posts (with images), and add other multimedia. +Having a docs+code monorepo is risky in the long term, as it couples all docs +built with code builds and vice versa. If docs CI fails because Netlify is +temporarily down, for example, this means that all your code builds can +potentially fail as well. Coupling docs in a repository with code can also make +a code repo's size expand exponentially, especially as projects pick up steam, +write more blog posts (with images), and add other multimedia. **A11y plan & implementation**: -The website meets the basic a11y requirements. The doc pages are readable. It is quite suitable as most website features are usable using a keyboard only. +The website meets the basic a11y requirements. The doc pages are readable. It is +quite suitable as most website features are usable using a keyboard only. **Mobile-first plan & impl.**: -This project makes sense as it is a [mobile-first](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) design. All website features are accessible from mobile -- such as the top-nav, site search, etc. +This project makes sense as it is a +[mobile-first](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first) +design. All website features are accessible from mobile -- such as the top-nav, +site search, etc. **HTTPS access & HTTP redirect**: The [website](https://gateway-api.sigs.k8s.io/) is accessible via HTTPS. - ### Recommendations **Branding and design**: -* We can add a _Copyright_ notice present at bottom of the page. \ -Copyright should be to the project authors or to CNCF, not the origin company. For details, see [Copyright notices](https://github.com/cncf/foundation/blob/master/copyright-notices.md). +- We can add a _Copyright_ notice present at bottom of the page. \ + Copyright should be to the project authors or to CNCF, not the origin company. + For details, see [Copyright notices](https://github.com/cncf/foundation/blob/master/copyright-notices.md). -* CNCF Branding elements - * “We are a Cloud Native Computing Foundation project.” or “We are a Cloud Native Computing Foundation sandbox project.” are present (depending on status) - * CNCF logo near the bottom of their project homepage - * _Optionally_ link to KubeCon + CloudNativeCon is the events approach +- CNCF Branding elements + - “We are a Cloud Native Computing Foundation project.” or “We are a Cloud + Native Computing Foundation sandbox project.” are present (depending on + status) + - CNCF logo near the bottom of their project homepage + - _Optionally_ link to KubeCon + CloudNativeCon is the events approach -* Page footer contents - * Trademark guidelines by either linking to Trademark Usage (directly or via a "Terms of Service" page) or by including the following text: -"The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see [Trademark Usage](https://www.linuxfoundation.org/trademark-usage/)". +- Page footer contents \* Trademark guidelines by either linking to Trademark + Usage (directly or via a "Terms of Service" page) or by including the + following text: "The Linux Foundation® (TLF) has registered trademarks and + uses trademarks. For a list of TLF trademarks, see + [Trademark Usage](https://www.linuxfoundation.org/trademark-usage/)". **Case studies/social proof**: -* We can write blog posts about experiences companies and projects using Gateway API. As you gather user blog posts over time, submit a ticket to the CNCF Service Desk and we can turn these into a more marketing-friendly case studies section on your site. +- We can write blog posts about experiences companies and projects using Gateway + API. As you gather user blog posts over time, submit a ticket to the CNCF + Service Desk and we can turn these into a more marketing-friendly case studies + section on your site. -* While ideally, we can have a logo wall of users or case studies, for a project of contour's size this is a great addition to the site. -* We should have a place to put case studies on a blog or similar though. +- While ideally, we can have a logo wall of users or case studies, for a project + of contour's size this is a great addition to the site. +- We should have a place to put case studies on a blog or similar though. **Maintenance planning**: @@ -230,12 +295,20 @@ We recommend housing the documentation in a separate repo. ### Reorganize your documentation's information architecture: -In addition to the suggestions above, I recommend an overall reorganization of the documentation, along with the top-level navigation of the site. +In addition to the suggestions above, I recommend an overall reorganization of +the documentation, along with the top-level navigation of the site. ### Revamping documentation for new users and new contributors -Moving to [Docsy](https://www.docsy.dev/), a Hugo theme, is highly recommended, for content organization and also if you decide to localize (translate) your content, as it has localization support built-in. In addition, it provides a lot of functionality that we'd be looking for (and it's the theme that [kubernetes.io](https://kubernetes.io/) uses). +Moving to [Docsy](https://www.docsy.dev/), a Hugo theme, is highly recommended, +for content organization and also if you decide to localize (translate) your +content, as it has localization support built-in. In addition, it provides a lot +of functionality that we'd be looking for (and it's the theme that +[kubernetes.io](https://kubernetes.io/) uses). -We can use one of the plugins that allow us to keep old versions of the site/documentation. This will make doing a fully-versioned site like the main Kubernetes site much easier. +We can use one of the plugins that allow us to keep old versions of the +site/documentation. This will make doing a fully-versioned site like the main +Kubernetes site much easier. -If you do ever decide to localize your content, it would be best to move the docs out of the code repo. +If you do ever decide to localize your content, it would be best to move the +docs out of the code repo. diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md index 625aecc..b13f95d 100644 --- a/analyses/0007-porter.md +++ b/analyses/0007-porter.md @@ -5,24 +5,28 @@ tags: porter # Notes -meeting notes: https://docs.google.com/document/d/12OGtSaUtlc7OA_iPnUvmVaiKg8yM7_QBzFnMgoHvnLw/edit?usp=sharing +meeting notes: +https://docs.google.com/document/d/12OGtSaUtlc7OA_iPnUvmVaiKg8yM7_QBzFnMgoHvnLw/edit?usp=sharing website: https://getporter.org/ -repos: -* https://github.com/getporter/porter (main site), site content is in docs/ folder -* https://github.com/getporter/operator (https://getporter.org/operator site) +repos: + +- https://github.com/getporter/porter (main site), site content is in docs/ + folder +- https://github.com/getporter/operator (https://getporter.org/operator site) # Porter Docs Assessment Prepared by: -* [Uchechukwu Obasi](https://github.com/thisisobate/) -* [Nate W.](https://github.com/nate-double-u/) -Date: 2023-04-07 +- [Uchechukwu Obasi](https://github.com/thisisobate/) +- [Nate W.](https://github.com/nate-double-u/) +Date: 2023-04-07 ## Introduction -This document assesses the quality and completeness of a project's documentation and website (if present). +This document assesses the quality and completeness of a project's documentation +and website (if present). This document: @@ -31,28 +35,29 @@ This document: - Provides examples of great documentation as reference - Identifies key improvements with the largest return on investment - ## How this document works The assessment is divided into three sections: -- **Project documentation:** for end users of the project; aimed at people who intend to use it -- **Contributor documentation:** for new and existing contributors to the project +- **Project documentation:** for end users of the project; aimed at people who + intend to use it +- **Contributor documentation:** for new and existing contributors to the + project - **Website:** branding, website structure, and maintainability Each section rates content based on different [criteria](criteria.md). - ## Project documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Information architecture | | | ✅ | | | -| New user content | | | | ✅ | | -| Content maintainability | ✅ | | | | | -| Content creation processes | | | | ✅ | | +| -------------------------- | --- | --- | --- | --- | --- | +| Information architecture | | | ✅ | | | +| New user content | | | | ✅ | | +| Content maintainability | ✅ | | | | | +| Content creation processes | | | | ✅ | | Scale: + - 1 = (Is not present or requires significant work) - 3 = (Is present, but needs work) - 5 = (Is executed extremely well or no improvement required) @@ -60,13 +65,19 @@ Scale: **Comments** ### Information architecture + - Good nav on landing page -- There appear to be two different operator quick starts (or is it the difference between desired state and operator? maybe the operator one needs to be in Get Started) - - https://getporter.org/quickstart/desired-state/ - - https://getporter.org/operator/quickstart/ +- There appear to be two different operator quick starts (or is it the + difference between desired state and operator? maybe the operator one needs to + be in Get Started) + + - https://getporter.org/quickstart/desired-state/ + - https://getporter.org/operator/quickstart/ -- Mixins & Plugins sections duplicated in sidebar (and could potentially be organized under Concepts?) +- Mixins & Plugins sections duplicated in sidebar (and could potentially be + organized under Concepts?) - Current info architecture + - root - Get started - Contribute @@ -79,122 +90,159 @@ Scale: - References - Judging by the git history, content is up to date. -- There is versioning on the site (it is easily missed though) - is there a process to help decide when content is stale? -- Lots of great examples, but there is no clear "happy path" through the content. I'm a new Porter user, what's considered a "basic" Porter setup, and how can I get there? +- There is versioning on the site (it is easily missed though) - is there a + process to help decide when content is stale? +- Lots of great examples, but there is no clear "happy path" through the + content. I'm a new Porter user, what's considered a "basic" Porter setup, and + how can I get there? ### New User content -- Porter's installation process is very well documented and well detailed in a step-by-step basis. -- Multiple OSes are well documented too. -- The onboarding and contributing guides are well documented making it easy for new users to understand and kickstart. +- Porter's installation process is very well documented and well detailed in a + step-by-step basis. +- Multiple OSes are well documented too. +- The onboarding and contributing guides are well documented making it easy for + new users to understand and kickstart. - Porter's sample code is copy-pastable. - "What is Porter?" is a good overview or 'about' section. -- Items listed under "When to use Porter?" are inconsistent with the way they're linked: some are linked while others are not. -- One can easily mistake Porter for Docker; it's hard to tell the difference between the two. +- Items listed under "When to use Porter?" are inconsistent with the way they're + linked: some are linked while others are not. +- One can easily mistake Porter for Docker; it's hard to tell the difference + between the two. - Main quick start links to Quickstart: Bundles - - is this the first thing a Porter user who wants to try out the system needs to see? - - quick start bundles feels more like a concepts page than a quick start + - is this the first thing a Porter user who wants to try out the system needs + to see? + - quick start bundles feels more like a concepts page than a quick start ### Content maintainability -- The project's website is located in the same repository as the project's source code. The maintainers argue it was done on purpose to encourage developers to write docs. I think it's a fair point. My only issue with this convention is that it makes it difficult for a new contributor to find the website's sourcefile. A contributor expects the "docs" directory to only contain nothing but actual documentation files not website sourcefiles. +- The project's website is located in the same repository as the project's + source code. The maintainers argue it was done on purpose to encourage + developers to write docs. I think it's a fair point. My only issue with this + convention is that it makes it difficult for a new contributor to find the + website's sourcefile. A contributor expects the "docs" directory to only + contain nothing but actual documentation files not website sourcefiles. - There's no way to search the documentation - Hard to locate the different versions on smaller screens ### Content creation processes -- The Contributing Guide contains really thorough documentation on contributing to both docs and the project itself! +- The Contributing Guide contains really thorough documentation on contributing + to both docs and the project itself! - Maintainers are clearly documented as well as where to find them. - There are no docs for the release process. Same for docs creation and updates. - **Recommendations** ### Information Architecture + - Overall, Porter's documentation is well organized: - - some pages seem misplaced (quick start for operator, ...) - - Some pages appear at the top level of the docs nav that may not need to be there -- search may help with findability - - Best practices could be under reference - - Mixins Plugins -- should these be top level? + - some pages seem misplaced (quick start for operator, ...) + - Some pages appear at the top level of the docs nav that may not need to be + there -- search may help with findability + - Best practices could be under reference + - Mixins Plugins -- should these be top level? ### New User content -- Document (or highlight) a new user's "happy path." Is there a particular config or deployment that most users would use? How could we highlight it? -- All the items listed under "When to use Porter?" section should maintain a consistent behavior; either make all items linkable or not. -- Create a docs detailing the difference between Porter and other bundling tools like Docker. -- The concept, Bundles, needs to be explained or defined at the top of the quickstart page. +- Document (or highlight) a new user's "happy path." Is there a particular + config or deployment that most users would use? How could we highlight it? +- All the items listed under "When to use Porter?" section should maintain a + consistent behavior; either make all items linkable or not. +- Create a docs detailing the difference between Porter and other bundling tools + like Docker. +- The concept, Bundles, needs to be explained or defined at the top of the + quickstart page. ### Content maintainability -- Move the website sourcefile to a separate "website" directory. That way, we create a good separation of concern. A good example is [https://github.com/thanos-io/thanos](https://github.com/thanos-io/thanos). +- Move the website sourcefile to a separate "website" directory. That way, we + create a good separation of concern. A good example is + [https://github.com/thanos-io/thanos](https://github.com/thanos-io/thanos). - The porter's docs should be searchable. -- Create a version picker (dropdown) to make search easily discoverable for users. +- Create a version picker (dropdown) to make search easily discoverable for + users. - Make version picker visible on smaller screens. ### Content Creation Process -- Create a doc detailing the code release process. This document should account for documentation creation & updates. +- Create a doc detailing the code release process. This document should account + for documentation creation & updates. ## Contributor documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | | ✅ | NW -| Beginner friendly issue backlog | | | | | ✅ | -| “New contributor” getting started content | | | | ✅ | | -| Project governance documentation | | | | | ✅ | +| ----------------------------------------- | --- | --- | --- | --- | --- | --- | +| Communication methods documented | | | | | ✅ | NW | +| Beginner friendly issue backlog | | | | | ✅ | +| “New contributor” getting started content | | | | ✅ | | +| Project governance documentation | | | | | ✅ | 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** + ### Communication methods documented -- Communication methods are clearly documented, as well as how (and where) to get calendar invites for meetings + +- Communication methods are clearly documented, as well as how (and where) to + get calendar invites for meetings ### Beginner friendly issue backlog + - Porter's issue templates are very good and helpful - The issue backlog is very beginner friendly and well groomed - Issue labels are very good, engaging and friendly. -- There seems to be no documentation around triage process (both for code issues and documentation issues that come up). +- There seems to be no documentation around triage process (both for code issues + and documentation issues that come up). ### “New contributor” getting started content + - Porter docs have a very good "new contributor" getting started content ### Project governance documentation + - Project governance is clearly documented **Recommendations** ### Beginner friendly issue backlog + - Create documentation around issue triage process. ### “New contributor” getting started content -- Make the new contributor guide to be easily accessible for new users on the website. A good idea is to link the "contribute" page from the homepage. + +- Make the new contributor guide to be easily accessible for new users on the + website. A good idea is to link the "contribute" page from the homepage. ### Project governance documentation -- Link governance docs from the website- a quick link on the community page would be helpful. + +- Link governance docs from the website- a quick link on the community page + would be helpful. ## Website | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Single-source for all files | | | ✅ | | | -| Meets min website req. (for maturity level) | | | | ✅ | | -| Branding and design | | | | | ✅ | -| Case studies/social proof | | | | ✅ | | -| Maintenance planning | | | | | ✅ | -| A11y plan & implementation | | | ✅ | | | -| Mobile-first plan & impl. | | | | | ✅ | -| HTTPS access & HTTP redirect | | | | | ✅ | -| Google Analytics 4 for production only | ✅ | | | | | -| Indexing allowed for production server only | | | | | ✅ | -| Intra-site / local search | ✅ | | | | | -| Account custodians are documented | | | | | ✅ | +| ------------------------------------------- | --- | --- | --- | --- | --- | +| Single-source for all files | | | ✅ | | | +| Meets min website req. (for maturity level) | | | | ✅ | | +| Branding and design | | | | | ✅ | +| Case studies/social proof | | | | ✅ | | +| Maintenance planning | | | | | ✅ | +| A11y plan & implementation | | | ✅ | | | +| Mobile-first plan & impl. | | | | | ✅ | +| HTTPS access & HTTP redirect | | | | | ✅ | +| Google Analytics 4 for production only | ✅ | | | | | +| Indexing allowed for production server only | | | | | ✅ | +| Intra-site / local search | ✅ | | | | | +| Account custodians are documented | | | | | ✅ | Scale: + - 1 = (Is not present or requires significant work) - 3 = (Is present, but needs work) - 5 = (Is executed extremely well or no improvement required) @@ -207,26 +255,36 @@ Scale: - website is mobile responsive - Website is accessible via HTTPS - Site is well-indexed on Google -- Account custodians are well documented +- Account custodians are well documented **Recommendations** + ### Single-source for all files + - Rename the "docs" directory to "website". ### Meets min website req. (for maturity level) -- Copyright and trademark footer should be present on all pages, not just home page. + +- Copyright and trademark footer should be present on all pages, not just home + page. ### Case studies/social proof + - create either a testimonial page or logo wall containing a list of adopters ### A11y plan & implementation -- Elements must have sufficient color contrast; case in point is the date class in the blog's page. Try increasing the contrast of the text color a little bit. + +- Elements must have sufficient color contrast; case in point is the date class + in the blog's page. Try increasing the contrast of the text color a little + bit. - Images must have an alt text - Ensure every id attribute value is unique ### Google Analytics 4 for production only -- Setup Google Analytics 4 for website. We advise you consult the CNCF to assist with this. + +- Setup Google Analytics 4 for website. We advise you consult the CNCF to assist + with this. ### Intra-site / local search -- Setup site-wide search for website. +- Setup site-wide search for website. diff --git a/analyses/0008-backstage/README.md b/analyses/0008-backstage/README.md index dcb57bd..eac162e 100644 --- a/analyses/0008-backstage/README.md +++ b/analyses/0008-backstage/README.md @@ -3,10 +3,21 @@ title: Backstage TechDocs Analysis tags: backstage --- -- [Backstage Doc Analysis](backstage-analysis.md) - Analyzes the existing Backstage documentation and provides recommendations. -- [Backstage Implementation](backstage-implementation.md) - Provides detailed and actionable recommendations, intended to be worked on as GitHub issues. -- [User Roles](user-roles.md) - A discussion of Backstage stakeholders with respect to how they use documentation. Folded into the Implementation doc. Reference. -- [Backstage Insights Summary](backstage-insights-summary.md) - A summary of conclusions from Spotify's survey of Backstage adopters. Background. -- [Backstage Issues](backstage-issues.md) - A list of documentation improvements derived from Backstage Implementation, to be entered as issues in the [backstage/backstage repo](https://github.com/backstage/backstage/issues/21893). -- [Backstage Docs Survey](backstage-doc-survey.csv) - A spreadsheet of every page of the Backstage technical documentation at the time of the analysis. About 200 lines. -- [Backstage Glossary](backstage-glossary.md) - A glossary of terms for the Backstage project, the Backstage product, and this analysis. Edit to use as the Glossary for the Backstage technical documentation. +- [Backstage Doc Analysis](backstage-analysis.md) - Analyzes the existing + Backstage documentation and provides recommendations. +- [Backstage Implementation](backstage-implementation.md) - Provides detailed + and actionable recommendations, intended to be worked on as GitHub issues. +- [User Roles](user-roles.md) - A discussion of Backstage stakeholders with + respect to how they use documentation. Folded into the Implementation doc. + Reference. +- [Backstage Insights Summary](backstage-insights-summary.md) - A summary of + conclusions from Spotify's survey of Backstage adopters. Background. +- [Backstage Issues](backstage-issues.md) - A list of documentation improvements + derived from Backstage Implementation, to be entered as issues in the + [backstage/backstage repo](https://github.com/backstage/backstage/issues/21893). +- [Backstage Docs Survey](backstage-doc-survey.csv) - A spreadsheet of every + page of the Backstage technical documentation at the time of the analysis. + About 200 lines. +- [Backstage Glossary](backstage-glossary.md) - A glossary of terms for the + Backstage project, the Backstage product, and this analysis. Edit to use as + the Glossary for the Backstage technical documentation. diff --git a/analyses/0008-backstage/backstage-analysis.md b/analyses/0008-backstage/backstage-analysis.md index eb53ee0..65675b6 100644 --- a/analyses/0008-backstage/backstage-analysis.md +++ b/analyses/0008-backstage/backstage-analysis.md @@ -8,13 +8,22 @@ author: Dave Welsch (@dwelsch-esi) # Introduction -This document analyzes the effectiveness and completeness of the [Backstage][backstage-io] 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 +[Backstage][backstage-io] 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. +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 was written to analyze the current state of Backstage documentation. It aims to provide project leaders with an informed understanding of their project documentation and to outline an actionable plan for improvement. +This document was written to analyze the current state of Backstage +documentation. It aims to provide project leaders with an informed understanding +of their project documentation and to outline an actionable plan for +improvement. This document: @@ -24,169 +33,264 @@ This document: ## Scope of analysis -The documentation discussed here includes the entire contents of the website (which contains the technical docs), as well as documentation for contributors and users on the Backstage GitHub repository. The analysis does not include Spotify's Backstage website at https://backstage.spotify.com/. +The documentation discussed here includes the entire contents of the website +(which contains the technical docs), as well as documentation for contributors +and users on the Backstage GitHub repository. The analysis does not include +Spotify's Backstage website at https://backstage.spotify.com/. -The Backstage website and documentation are written in Markdown and are compiled using the Docusaurus static site generator. The site's code is stored on the Backstage GitHub repo. +The Backstage website and documentation are written in Markdown and are compiled +using the Docusaurus static site generator. The site's code is stored on the +Backstage GitHub repo. **In scope:** + - Website: https://backstage.io - Documentation: https://backstage.io/docs -- Contributor documentation: +- Contributor documentation: - https://github.com/backstage/backstage/README.md - https://github.com/backstage/backstage/CONTRIBUTING.md -- Website configuration (Docusaurus): https://github.com/backstage/backstage/microsite +- Website configuration (Docusaurus): + https://github.com/backstage/backstage/microsite - Website content: https://github.com/backstage/backstage/docs **Out of scope:** -- Backstage plugins: https://backstage.spotify.com/ +- Backstage plugins: https://backstage.spotify.com/ ## How this document is organized -This document is divided into three sections that represent three major areas of concern: +This document is divided into three sections that represent three major areas of +concern: -- **Project documentation:** concerns documentation for users of the Backstage software, aimed at people who intend to use it -- **Contributor documentation:** concerns documentation for new and existing contributors to the Backstage OSS project -- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability +- **Project documentation:** concerns documentation for users of the Backstage + software, aimed at people who intend to use it +- **Contributor documentation:** concerns documentation for new and existing + contributors to the Backstage OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability -Each section begins with summary ratings based on a rubric with appropriate [criteria][cncf-doc-criteria] for the section, then proceeds to: -- **Comments**: observations about the existing documentation, with a focus on how it does or does not help Backstage users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness of the documentation. +Each section begins with summary ratings based on a rubric with appropriate +[criteria][cncf-doc-criteria] for the section, then proceeds to: -An accompanying document, [backstage-implementation.md][implementation-doc], 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 should be tracked as a series of Github [issues][backstage-issues]. +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help Backstage users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. +An accompanying document, [backstage-implementation.md][implementation-doc], +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 should be tracked as a series of Github +[issues][backstage-issues]. ## How to use this document -Readers interested only in actionable improvements should skip this document and read [backstage-implementation.md][implementation-doc]. +Readers interested only in actionable improvements should skip this document and +read [backstage-implementation.md][implementation-doc]. -Readers interested in the current state of the documentation and the reasoning behind the recommendations should read this document or the section pertaining to their area of concern: +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read this document or the section pertaining +to their area of concern: - [Project documentation][proj-doc] - [Contributor documentation][contributor-doc] - [Website and documentation infrrastructure][website] -Examples of CNCF documentation that demonstrates the analysis criteria are linked from the [Criteria][cncf-doc-criteria] specification. - +Examples of CNCF documentation that demonstrates the analysis criteria are +linked from the [Criteria][cncf-doc-criteria] specification. ### Recommendations, requirements, and best practices -Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, 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 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. - +Notwithstanding the fact that this analysis measures documentation against CNCF +project maturity standards, 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 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. # Project documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Information architecture | | ✔︎ | | | | -| New user content | | | | ✔︎ | | -| Content maintainability | | | ✔︎ | | | -| Content creation processes | | | ✔︎ | | | -| Inclusive language | | | | ✔︎ | | +| -------------------------- | --- | --- | --- | --- | --- | +| Information architecture | | ✔︎ | | | | +| New user content | | | | ✔︎ | | +| Content maintainability | | | ✔︎ | | | +| Content creation processes | | | ✔︎ | | | +| Inclusive language | | | | ✔︎ | | 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: project documentation -Backstage is a platform for organizing and managing software projects. This complicates the documentation, because it can be difficult to distinguish among several levels of involvement with Backstage: - -1. Use of Backstage as an organizational contributor (coder, DevOp, tech writer) to catalog, create, or document software. -2. Administration of a Backstage instance ("app" in Backstage nomenclature), including installation, deployment, software upgrades, configuration, and customization using plugins. -3. Extending a Backstage app, including writing plugins and modifying existing plugins. +Backstage is a platform for organizing and managing software projects. This +complicates the documentation, because it can be difficult to distinguish among +several levels of involvement with Backstage: + +1. Use of Backstage as an organizational contributor (coder, DevOp, tech writer) + to catalog, create, or document software. +2. Administration of a Backstage instance ("app" in Backstage nomenclature), + including installation, deployment, software upgrades, configuration, and + customization using plugins. +3. Extending a Backstage app, including writing plugins and modifying existing + plugins. 4. Modification or extension of the Backstage platform. -This complexity necessitates clear definitions of roles so that use cases can be documented, indexed, found, and used. The four levels described above suggest that documentation should be organized under at least four roles: +This complexity necessitates clear definitions of roles so that use cases can be +documented, indexed, found, and used. The four levels described above suggest +that documentation should be organized under at least four roles: 1. Using Backstage for software development: end user. -2. Installing and maintaining a Backstage app for an organization: Backstage admin. +2. Installing and maintaining a Backstage app for an organization: Backstage + admin. 3. Extending a Backstage app: DevOp or internal tooling developer. 4. Extending the Backstage platform: contributing developer. ### Overall Issues The main issues with the Backstage documentation are: + 1. Lack of organization around user roles, and -2. Lack of instructional content that defines tasks for each role and provides explicit instructions to accomplish these tasks. +2. Lack of instructional content that defines tasks for each role and provides + explicit instructions to accomplish these tasks. + +For example, the [Overview][backstage-io-overview] contains valuable high-level +conceptual information, including a list of +[benefits][backstage-io-overview-benefits] to particular user roles (engineering +managers, developers, platform engineers). This demonstrates awareness of user +roles that needs to be extended throughout the documentation. -For example, the [Overview][backstage-io-overview] contains valuable high-level conceptual information, including a list of [benefits][backstage-io-overview-benefits] to particular user roles (engineering managers, developers, platform engineers). This demonstrates awareness of user roles that needs to be extended throughout the documentation. +There are installation and configuration instructions in [Getting +Started][backstage-doc-getting-started]. However: -There are installation and configuration instructions in [Getting Started][backstage-doc-getting-started]. However: 1. The instructions describe a local installation. 2. The user documentation, for the most part, lacks procedural information. -The following sections contain brief analyses of each element of the Project Documentation rubric. +The following sections contain brief analyses of each element of the Project +Documentation rubric. ### Information architecture -**Conceptual content** is abundant throughout the Backstage documentation. This is good, because using Backstage effectively requires a thorough understanding of its information model. +**Conceptual content** is abundant throughout the Backstage documentation. This +is good, because using Backstage effectively requires a thorough understanding +of its information model. -The documentation seems **feature complete**. All software features are documented. +The documentation seems **feature complete**. All software features are +documented. -**Instructional content** is a weakness of the Backstage docs. In many cases, tasks required of each role are missing, as are instructions for completing these tasks. Instructional material for the most common use cases (**"happy path"**) should support learning (tutorials) as well as doing (procedures). Where instructional content exists, it is often: +**Instructional content** is a weakness of the Backstage docs. In many cases, +tasks required of each role are missing, as are instructions for completing +these tasks. Instructional material for the most common use cases (**"happy +path"**) should support learning (tutorials) as well as doing (procedures). +Where instructional content exists, it is often: - Not aimed at a defined user, - Not clearly identified as instructional content, or -- Intermingled or confused with reference information (for example, many configuration "how-tos" are in the form of a list of YAML properties). - -**Escalation** options (FAQs, Troubleshooting docs) exist for most Backstage functionality. As well, the contributor community provides robust support (GitHub [issues][backstage-issues] and discussion channels). - -**Reference information** exists, including for **APIs**, but is scattered throughout the documentation. - -**Organizing individual pages**: A [survey of the existing documentation][doc-survey] suggests a general issue with many individual pages: trying to include too much information on one page. Often a task is mixed with reference information or with more conceptual information than is necessary to support the task. Effective documentation focuses on one type of information per page, especially when presenting instructional content: the page should present only what information is necessary to do the task, and nothing else. Examples of information that should be on a different (but linked) page: Explanations of the task's purpose; command references (except the exact commands needed to complete the task); and examples, such as config file entries (again, except as necessary). - -It's not clear that the documentation is completely **up to date**, although [release notes][backstage-doc-rn] exist and are easily findable. - +- Intermingled or confused with reference information (for example, many + configuration "how-tos" are in the form of a list of YAML properties). + +**Escalation** options (FAQs, Troubleshooting docs) exist for most Backstage +functionality. As well, the contributor community provides robust support +(GitHub [issues][backstage-issues] and discussion channels). + +**Reference information** exists, including for **APIs**, but is scattered +throughout the documentation. + +**Organizing individual pages**: A [survey of the existing +documentation][doc-survey] suggests a general issue with many individual pages: +trying to include too much information on one page. Often a task is mixed with +reference information or with more conceptual information than is necessary to +support the task. Effective documentation focuses on one type of information per +page, especially when presenting instructional content: the page should present +only what information is necessary to do the task, and nothing else. Examples of +information that should be on a different (but linked) page: Explanations of the +task's purpose; command references (except the exact commands needed to complete +the task); and examples, such as config file entries (again, except as +necessary). + +It's not clear that the documentation is completely **up to date**, although +[release notes][backstage-doc-rn] exist and are easily findable. ### New user content -**New user** content is present and findable ("**signposted**"), including **installation** instructions for all applicable **OSes**. However, the [Getting Started][backstage-doc-getting-started] instructions don't distinguish between administrator and developer end-user roles. [Deployment][backstage-doc-deployment] describes various scenarios for administrators, but doesn't provide end-to-end instructions. There is no clear workflow **path** after installation. - -There is **example content** available, including tutorials for a variety of tasks and a very nice [demo server][backstage-demo]. +**New user** content is present and findable ("**signposted**"), including +**installation** instructions for all applicable **OSes**. However, the [Getting +Started][backstage-doc-getting-started] instructions don't distinguish between +administrator and developer end-user roles. +[Deployment][backstage-doc-deployment] describes various scenarios for +administrators, but doesn't provide end-to-end instructions. There is no clear +workflow **path** after installation. +There is **example content** available, including tutorials for a variety of +tasks and a very nice [demo server][backstage-demo]. ### Content maintainability & site mechanics -The documentation is **searchable**. There does not seem to be a **localization** framework. There doesn't currently seem to be any kind of localization effort. - -There does not seem to be any mechanism for **versioning** documentation content. +The documentation is **searchable**. There does not seem to be a +**localization** framework. There doesn't currently seem to be any kind of +localization effort. +There does not seem to be any mechanism for **versioning** documentation +content. ### Content creation processes -The procedures for duplicating the documentation locally and for contributing documentation are [documented][backstage-microsite] but are [not easily findable][backstage-doc-contrib]. +The procedures for duplicating the documentation locally and for contributing +documentation are [documented][backstage-microsite] but are [not easily +findable][backstage-doc-contrib]. -These procedures are presumably included in any updates to (and subsequent **release** of) the project code (since the doc is in the same GitHub repo). **Reviewers and approvers** are presumably the Backstage OSS community at large. It would be nice if this situation were made clear explicitly. +These procedures are presumably included in any updates to (and subsequent +**release** of) the project code (since the doc is in the same GitHub repo). +**Reviewers and approvers** are presumably the Backstage OSS community at large. +It would be nice if this situation were made clear explicitly. The website does not have a clear individual **owner or maintainer**. - ### Inclusive language -I found no content that uses non-recommended words as documented by the [Inclusive Naming Initiative][inclusive-naming] website. - -The website makes occasional use of words like "simple" and "easy", but avoids explicitly ableist language. +I found no content that uses non-recommended words as documented by the +[Inclusive Naming Initiative][inclusive-naming] website. +The website makes occasional use of words like "simple" and "easy", but avoids +explicitly ableist language. ## Recommendations: project documentation -The following sections contain recommendations for improvements to the Backstage project documentation. These recommendations are for broad improvements that would greatly increase documentation effectiveness. For details, see [Implementation][implementation]. - +The following sections contain recommendations for improvements to the Backstage +project documentation. These recommendations are for broad improvements that +would greatly increase documentation effectiveness. For details, see +[Implementation][implementation]. ### Clarify user roles and objectives -Any systemic improvement to the Backstage documentation hinges on clearly defining and documenting user roles. This is a first step in defining any documentation set, but the nature of Backstage makes it especially important here. - -The example roles given in the [comments][proj-doc-comments] have been carried over to the [Implementation][implementation] section. Contributors with a greater understanding of how Backstage is used should feel free to modify this list if it serves the needs of the project, keeping in mind that the purpose of the user roles is to organize the task-based documentation. +Any systemic improvement to the Backstage documentation hinges on clearly +defining and documenting user roles. This is a first step in defining any +documentation set, but the nature of Backstage makes it especially important +here. +The example roles given in the [comments][proj-doc-comments] have been carried +over to the [Implementation][implementation] section. Contributors with a +greater understanding of how Backstage is used should feel free to modify this +list if it serves the needs of the project, keeping in mind that the purpose of +the user roles is to organize the task-based documentation. ### Develop instructional documentation -Most of the Backstage documentation seems to have evolved from architecture and design documentation. This makes it very rich in conceptual material and reference documentation, but weak in user-oriented instructional documentation. +Most of the Backstage documentation seems to have evolved from architecture and +design documentation. This makes it very rich in conceptual material and +reference documentation, but weak in user-oriented instructional documentation. -"Instructional documentation" is a broad category that includes such traditional documentation artifacts as tutorials; getting started guides; procedural recipes or "cookbooks"; runbooks; and how-to guides. +"Instructional documentation" is a broad category that includes such traditional +documentation artifacts as tutorials; getting started guides; procedural recipes +or "cookbooks"; runbooks; and how-to guides. For every user role: @@ -194,106 +298,147 @@ For every user role: Define the common use cases for each role. Some typical examples: -*Administrator*: Installation; deployment; configuration; maintenance; upgrades; extension (plugins); disaster recovery. +_Administrator_: Installation; deployment; configuration; maintenance; upgrades; +extension (plugins); disaster recovery. -*User (developer)*: Development environment setup; Adding an existing element; creating a new element; creating a template; viewing projects; searching; creating documentation; CI/CD; deploying; reverting a deployment. +_User (developer)_: Development environment setup; Adding an existing element; +creating a new element; creating a template; viewing projects; searching; +creating documentation; CI/CD; deploying; reverting a deployment. **Write procedures** -For each use case, develop instructional content, including: "happy path" procedures that can be followed by anyone familiar with the product generally; examples; troubleshooting guides; and for new users, tutorials. +For each use case, develop instructional content, including: "happy path" +procedures that can be followed by anyone familiar with the product generally; +examples; troubleshooting guides; and for new users, tutorials. **Support procedures with conceptual and reference topics** -Much of the existing documentation can and should be re-used when possible. Existing documentation pages should be analyzed by type of content (this analysis has already been done; see the [documentation survey][doc-survey]). Pages should be rewritten so that each page serves one purpose: conceptual, task, or reference. In some cases this will mean that two pages are extracted from a single existing page. Conversely, some pages may prove to be redundant. The new, more focused pages can then be reorganized as described below. - +Much of the existing documentation can and should be re-used when possible. +Existing documentation pages should be analyzed by type of content (this +analysis has already been done; see the [documentation survey][doc-survey]). +Pages should be rewritten so that each page serves one purpose: conceptual, +task, or reference. In some cases this will mean that two pages are extracted +from a single existing page. Conversely, some pages may prove to be redundant. +The new, more focused pages can then be reorganized as described below. ### Reorganize the documentation site -Right now different types of documentation (conceptual/architectural; instructional; reference) for different user roles are intermixed throughout the documentation site. +Right now different types of documentation (conceptual/architectural; +instructional; reference) for different user roles are intermixed throughout the +documentation site. **Organize by role and task** -The site should be reorganized based on an overarching principle of grouping together documentation needed by a particular user role for a particular set of tasks. This sounds daunting, but it's the schema behind a traditional developer documentation suite, which can be used as a model. For an example of such a doc suite, see [this blog post][esi-doc-suite]. Or [this one][esi-doc-spec] on how to think about a doc specification. [This survey of the existing Backstage doc pages][doc-survey] suggests where each page might fit if the doc were reorganized in this manner. +The site should be reorganized based on an overarching principle of grouping +together documentation needed by a particular user role for a particular set of +tasks. This sounds daunting, but it's the schema behind a traditional developer +documentation suite, which can be used as a model. For an example of such a doc +suite, see [this blog post][esi-doc-suite]. Or [this one][esi-doc-spec] on how +to think about a doc specification. [This survey of the existing Backstage doc +pages][doc-survey] suggests where each page might fit if the doc were +reorganized in this manner. **Provide adequate navigation signals** -Reorganizing the site will make the documentation more usable. Not to be overlooked is the companion task of making the documentation *findable*. This involves creating adequate tables of contents (TOCs), indexes, and a glossary to help navigate the site. Much of this is automated by the static site generator (currently *Docusaurus*), but it's the writer's responsibility to assure that these navigation aids are adequate. - +Reorganizing the site will make the documentation more usable. Not to be +overlooked is the companion task of making the documentation _findable_. This +involves creating adequate tables of contents (TOCs), indexes, and a glossary to +help navigate the site. Much of this is automated by the static site generator +(currently _Docusaurus_), but it's the writer's responsibility to assure that +these navigation aids are adequate. # Contributor documentation | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | ✔︎ | | -| Beginner friendly issue backlog | | | | ✔︎ | | -| “New contributor” getting started content | | | ✔︎ | | | -| Project governance documentation | | | | | ✔︎ | +| ----------------------------------------- | --- | --- | --- | --- | --- | +| Communication methods documented | | | | ✔︎ | | +| Beginner friendly issue backlog | | | | ✔︎ | | +| “New contributor” getting started content | | | ✔︎ | | | +| Project governance documentation | | | | | ✔︎ | 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: contributor documentation -A unique feature of Backstage is that user and contributor roles exist on a spectrum; plugins designed or modified to serve a particular organization can be contributed to the Backstage project, or can originate there in anticipation of a particular organization's need. As a result, documentation for project contributors is intermingled, and easily confused, with instructions for admin users trying to expand functionality by modifying or adding code, especially plugins. - +A unique feature of Backstage is that user and contributor roles exist on a +spectrum; plugins designed or modified to serve a particular organization can be +contributed to the Backstage project, or can originate there in anticipation of +a particular organization's need. As a result, documentation for project +contributors is intermingled, and easily confused, with instructions for admin +users trying to expand functionality by modifying or adding code, especially +plugins. ### Communication methods documented -Communication channels are clearly documented on the [Community][backstage-community] page of the website, including **message channels**, **newsletters** and **adoption meetings**. There is some minor conflation of commercially sponsored content on the community page. - -The **[GitHub][backstage-backstage] repository** is directly linked from the main menu. There are 22 related repositories listed on the [Backstage project page][backstage-github-project]. A little digging is required to suss out the purpose of some of these projects. +Communication channels are clearly documented on the +[Community][backstage-community] page of the website, including **message +channels**, **newsletters** and **adoption meetings**. There is some minor +conflation of commercially sponsored content on the community page. +The **[GitHub][backstage-backstage] repository** is directly linked from the +main menu. There are 22 related repositories listed on the [Backstage project +page][backstage-github-project]. A little digging is required to suss out the +purpose of some of these projects. ### Beginner friendly issue backlog -The backlog is robustly **triaged** and documented. A **"good first issue"** label is available and prominently recommended. Issues are **well documented** with complete descriptions. +The backlog is robustly **triaged** and documented. A **"good first issue"** +label is available and prominently recommended. Issues are **well documented** +with complete descriptions. -There are quite a few **stale backlog items** open in the backlog list. Many, perhaps a majority, of these seem to be plugin requests. +There are quite a few **stale backlog items** open in the backlog list. Many, +perhaps a majority, of these seem to be plugin requests. ### New contributor getting started content -The Backstage OSS **community** is visible and accessible on a [community page][backstage-community] reached via a top-level menu item on the website. There is an active [Discussions][backstage-discussion] board in the GitHub repo. +The Backstage OSS **community** is visible and accessible on a [community +page][backstage-community] reached via a top-level menu item on the website. +There is an active [Discussions][backstage-discussion] board in the GitHub repo. **[Contributor guidelines][backstage-contrib]** are provided. -**Help** is available in any of the discussion groups and through a [community page][backstage-github-community] on GitHub. Help resources are not linked from the Getting Started documentation. +**Help** is available in any of the discussion groups and through a [community +page][backstage-github-community] on GitHub. Help resources are not linked from +the Getting Started documentation. Backstage is listed in the [Clotributor][clotributor] tool. - ### Project governance documentation Governance is clearly documented in [GOVERNANCE.md][backstage-governance]. - ## Recommendations: contributor documentation As an open source project, Backstage looks healthy and well run. -The only recommendation here is to disentangle the contributor documentation from the product documentation, as described in the [Information architecture recommendations][info-arch-recommend]. - +The only recommendation here is to disentangle the contributor documentation +from the product documentation, as described in the [Information architecture +recommendations][info-arch-recommend]. # Website | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Single source for all files | | | ✔︎ | | | -| Meets min website req. (for maturity level) | | ✔︎ | | | | -| Branding and design | | | | ✔︎ | | -| Case studies/social proof | | | ✔︎ | | | -| SEO, Analytics, and site-local search | | | | | ✔︎ | -| Maintenance planning | | | ✔︎ | | | -| A11y plan & implementation | | | | ✔︎ | | -| Mobile-first plan & impl. | | | ✔︎ | | | -| HTTPS access & HTTP redirect | | | | | ✔︎ | -| Google Analytics 4 for production only | | | | | ✔︎ | -| Indexing allowed for production server only | | | | | ✔︎ | -| Intra-site / local search | | | | | ✔︎ | -| Account custodians are documented | ✔︎ | | | | | +| ------------------------------------------- | --- | --- | --- | --- | --- | +| Single source for all files | | | ✔︎ | | | +| Meets min website req. (for maturity level) | | ✔︎ | | | | +| Branding and design | | | | ✔︎ | | +| Case studies/social proof | | | ✔︎ | | | +| SEO, Analytics, and site-local search | | | | | ✔︎ | +| Maintenance planning | | | ✔︎ | | | +| A11y plan & implementation | | | | ✔︎ | | +| Mobile-first plan & impl. | | | ✔︎ | | | +| HTTPS access & HTTP redirect | | | | | ✔︎ | +| Google Analytics 4 for production only | | | | | ✔︎ | +| Indexing allowed for production server only | | | | | ✔︎ | +| Intra-site / local search | | | | | ✔︎ | +| Account custodians are documented | ✔︎ | | | | | Scale: + - 1 = (Is not present or requires significant work) - 3 = (Is present, but needs work) - 5 = (Is executed extremely well or no improvement required) @@ -302,55 +447,61 @@ Scale: ### Single-source requirement -The source files for the website and technical documentation reside in two separate directories of the Backstage GitHub repo, built as a single unit by *Docusaurus*. There is no separate **website repo**. +The source files for the website and technical documentation reside in two +separate directories of the Backstage GitHub repo, built as a single unit by +_Docusaurus_. There is no separate **website repo**. -The strategy for **generating the docs** is documented but obscure. +The strategy for **generating the docs** is documented but obscure. ### Minimal website requirements -Listed and acknowledged below are the (cumulative) _minimal_ website requirements for projects based on their [maturity level][cncf-maturity-stages]: sandbox, incubating, graduated and archived. - -| Maturity | Requirement | Met? | -| --- | --- | --- | -| Sandbox | Majority of [Website guidelines][cncf-website-guidelines] satisfied | yes | -| Sandbox | [Docs analysis][cncf-docs-howto] [submitting a request][cncf-servicedesk] completed. | yes | -| Incubating | All [Website guidelines][cncf-doc-criteria] satisfied | no | -| Incubating | Request docs (re-)analysis through CNCF [service desk][cncf-servicedesk] | yes | -| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | no | -| Incubating | **Project doc**: Hosted directly | yes | -| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | no | -| Graduated | [Docs analysis][cncf-docs-howto]: all analysis follow-through actions are complete | no | -| Graduated | **Project doc** fully addresses needs of key stakeholders | no | -| Archived | The website repo is in an [archived state][github-archiving] | n/a | -| Archived | Archived status of the project is obvious to site visitors | n/a | -| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a | - +Listed and acknowledged below are the (cumulative) _minimal_ website +requirements for projects based on their [maturity level][cncf-maturity-stages]: +sandbox, incubating, graduated and archived. + +| Maturity | Requirement | Met? | +| ---------- | ------------------------------------------------------------------------------------ | ---- | +| Sandbox | Majority of [Website guidelines][cncf-website-guidelines] satisfied | yes | +| Sandbox | [Docs analysis][cncf-docs-howto] [submitting a request][cncf-servicedesk] completed. | yes | +| Incubating | All [Website guidelines][cncf-doc-criteria] satisfied | no | +| Incubating | Request docs (re-)analysis through CNCF [service desk][cncf-servicedesk] | yes | +| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | no | +| Incubating | **Project doc**: Hosted directly | yes | +| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | no | +| Graduated | [Docs analysis][cncf-docs-howto]: all analysis follow-through actions are complete | no | +| Graduated | **Project doc** fully addresses needs of key stakeholders | no | +| Archived | The website repo is in an [archived state][github-archiving] | n/a | +| Archived | Archived status of the project is obvious to site visitors | n/a | +| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a | ### Branding and design -The Backstage **brand** is easily recognizable through the logo and color scheme. The scheme is **used consistently** across the website and docs. +The Backstage **brand** is easily recognizable through the logo and color +scheme. The scheme is **used consistently** across the website and docs. The website **typography** is easy to read. - ### Case studies/social proof -**Case studies** and **testimonials** are not prominent and are not readily findable from the website. There is no **logo wall** of participating organizations. - -The project has an **active blog**. **Community discussions** are available on the website. +**Case studies** and **testimonials** are not prominent and are not readily +findable from the website. There is no **logo wall** of participating +organizations. +The project has an **active blog**. **Community discussions** are available on +the website. ### SEO, Analytics and site-local search **Analytics** - - **Analytics** is enabled for the production server using **GA4**. - - Analytics is **disabled for all other deploys**. - - **Page-not-found (404) reports** are easily generated from the site. +- **Analytics** is enabled for the production server using **GA4**. +- Analytics is **disabled for all other deploys**. +- **Page-not-found (404) reports** are easily generated from the site. **Site indexing** - **Indexing** is supported for the **production server**. Indexing is **disabled for previews** and **non-default builds** automatically with `plugin-sitemap`. +**Indexing** is supported for the **production server**. Indexing is **disabled +for previews** and **non-default builds** automatically with `plugin-sitemap`. **Search** @@ -358,8 +509,9 @@ Local intra-site **search** is available from the website. **Custodians** -The current **custodian(s)** of the following accounts are **not** clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia). - +The current **custodian(s)** of the following accounts are **not** clearly +documented: analytics, Google Search Console, site-search (such as Google CSE or +Algolia). ### Maintenance planning @@ -367,90 +519,113 @@ The **website tooling** (Docusaurus static site build) is well supported. **Cultivation of website maintainers** from within the community is inadequate. -I tested the instructions for using `yarn` to build the website. The **site build time** was under 30 seconds for a local build on a Mac M1. Maintainers have sufficient **permissions** to download and build the doc. Checking in the doc requires a PR and approval from a project maintainer. - +I tested the instructions for using `yarn` to build the website. The **site +build time** was under 30 seconds for a local build on a Mac M1. Maintainers +have sufficient **permissions** to download and build the doc. Checking in the +doc requires a PR and approval from a project maintainer. ### Usability, accessibility and devices -Backstage.io is partially conformant with [WCAG 2.1 level AA][wcag-understanding] with respect to **accessibility**. - +Backstage.io is partially conformant with [WCAG 2.1 level +AA][wcag-understanding] with respect to **accessibility**. ## Recommendations: website ### Single-source repo -The documentation is isolated from the code by virtue of being in its own directories; however, its location and build instructions are hard to find. Write explicit instructions for contributing to documentation. Make these instructions prominent in the contributor guidelines. Emphasize the importance of keeping the documentation directories separate from code. - -An even better plan would be to extract the Docusaurus configurations and website documentation to their own repository. The Backstage project already has many repositories. Creating one more for documentation would make the project organization cleaner and make it easier to contribute to the project documentation. +The documentation is isolated from the code by virtue of being in its own +directories; however, its location and build instructions are hard to find. +Write explicit instructions for contributing to documentation. Make these +instructions prominent in the contributor guidelines. Emphasize the importance +of keeping the documentation directories separate from code. +An even better plan would be to extract the Docusaurus configurations and +website documentation to their own repository. The Backstage project already has +many repositories. Creating one more for documentation would make the project +organization cleaner and make it easier to contribute to the project +documentation. ### Minimum website requirements for maturity level -To meet the maturity level standards for a graduated project, the following aspects should be updated as described in [Project documentation][proj-doc]: +To meet the maturity level standards for a graduated project, the following +aspects should be updated as described in [Project documentation][proj-doc]: - Identify the project and product stakeholder roles. - Analyze stakeholder needs. -- Update and reorganize the documentation with respect to user orientation and task-based support of use cases. - +- Update and reorganize the documentation with respect to user orientation and + task-based support of use cases. ### Case studies/social proof -Implement a **logo wall** of participating organizations, with links to testimonials and/or case studies. - +Implement a **logo wall** of participating organizations, with links to +testimonials and/or case studies. ### SEO, Analytics and site-local search -Add documentation and website custodians to the project maintainer lists in `OWNERS.md` and wherever else project maintainers are documented. - +Add documentation and website custodians to the project maintainer lists in +`OWNERS.md` and wherever else project maintainers are documented. ### Maintenance planning -Add a prominent call for website and documentation maintainers in the project introduction alongside the call for code maintainers. - +Add a prominent call for website and documentation maintainers in the project +introduction alongside the call for code maintainers. ### Accessibility Improve compliance in these areas: + - **Images** should have alternative text. - **Links** should have discernible text. - [backstage-backstage]: https://github.com/backstage/backstage [backstage-community]: https://backstage.io/community [backstage-contrib]: https://github.com/backstage/backstage/CONTRIBUTING.md -[backstage-demo]: https://demo.backstage.io/catalog?filters%5Bkind%5D=component&filters%5Buser%5D=owned +[backstage-demo]: + https://demo.backstage.io/catalog?filters%5Bkind%5D=component&filters%5Buser%5D=owned [backstage-discussion]: https://github.com/backstage/backstage/discussions -[backstage-doc-contrib]: https://backstage.io/docs/getting-started/getting-involved#write-documentation-or-improve-the-website +[backstage-doc-contrib]: + https://backstage.io/docs/getting-started/getting-involved#write-documentation-or-improve-the-website [backstage-doc-deployment]: https://backstage.io/docs/deployment/ [backstage-doc-getting-started]: https://backstage.io/docs/getting-started/ [backstage-doc-rn]: https://backstage.io/docs/releases/v1.17.0 [backstage-github-community]: https://github.com/backstage/community [backstage-github-project]: https://github.com/backstage -[backstage-governance]: https://github.com/backstage/backstage/blob/master/GOVERNANCE.md +[backstage-governance]: + https://github.com/backstage/backstage/blob/master/GOVERNANCE.md [backstage-insights-summary]: ./backstage-insights-summary.md [backstage-issues]: https://github.com/backstage/backstage/issues -[backstage-io-overview-benefits]: https://backstage.io/docs/overview/what-is-backstage#benefits +[backstage-io-overview-benefits]: + https://backstage.io/docs/overview/what-is-backstage#benefits [backstage-io-overview]: https://backstage.io/docs/overview/what-is-backstage [backstage-io]: https://backstage.io -[backstage-microsite]: https://github.com/backstage/backstage/tree/master/microsite +[backstage-microsite]: + https://github.com/backstage/backstage/tree/master/microsite [clotributor]: https://clotributor.dev/ [cncf-doc-criteria]: ../criteria.md -[cncf-doc-criteria]: https://github.com/cncf/techdocs/blob/main/assessments/criteria.md -[cncf-docs-howto]: https://github.com/cncf/techdocs/blob/main/assessments/howto.md -[cncf-maturity-stages]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[cncf-doc-criteria]: + https://github.com/cncf/techdocs/blob/main/assessments/criteria.md +[cncf-docs-howto]: + https://github.com/cncf/techdocs/blob/main/assessments/howto.md +[cncf-maturity-stages]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [cncf-servicedesk]: https://servicedesk.cncf.io [cncf-website-guidelines]: ../../docs/website-guidelines-checklist.md [dwelsch-esi-github]: https://github.com/dwelsch-esi/ -[esi-doc-spec]: https://expertsupport.com/library/quick-and-easy-document-specifications/ -[esi-doc-suite]: https://expertsupport.com/library/the-ideal-documentation-suite-for-software-developers/ -[github-archiving]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories +[esi-doc-spec]: + https://expertsupport.com/library/quick-and-easy-document-specifications/ +[esi-doc-suite]: + https://expertsupport.com/library/the-ideal-documentation-suite-for-software-developers/ +[github-archiving]: + https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories [implementation-doc]: ./backstage-implementation.md [inclusive-naming]: https://inclusivenaming.org [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 [wcag-understanding]: https://www.w3.org/WAI/WCAG21/Understanding/ + + [contrib-doc-rec]: #recommendations-contributor-documentation [contributor-doc]: #contributor-documentation [doc-survey]: ./Backstage%20doc%20survey.csv diff --git a/analyses/0008-backstage/backstage-glossary.md b/analyses/0008-backstage/backstage-glossary.md index f1fc5a8..eb174ea 100644 --- a/analyses/0008-backstage/backstage-glossary.md +++ b/analyses/0008-backstage/backstage-glossary.md @@ -2,23 +2,29 @@ ## API -In the Backstage [Catalog](#catalog), an API is an [entity](#entity) representing a boundary between two [compnents](#component). +In the Backstage [Catalog](#catalog), an API is an [entity](#entity) +representing a boundary between two [compnents](#component). https://backstage.io/docs/features/software-catalog/system-model ## Administrator -Someone responsible for installing and maintaining a Backstage [app](#app) for an organization. A [user role](#user-role). +Someone responsible for installing and maintaining a Backstage [app](#app) for +an organization. A [user role](#user-role). ## App -An installed instance of Backstage. An app can be local, intended for a single development group or individual developer, or organizational, for use by an entire enterprise. +An installed instance of Backstage. An app can be local, intended for a single +development group or individual developer, or organizational, for use by an +entire enterprise. ## Backstage -A platform for creating and deploying [developer portals](#developer-portal), originally created at Spotify. +A platform for creating and deploying [developer portals](#developer-portal), +originally created at Spotify. -Backstage is an incubation-stage open source project of the [Cloud Native Computing Foundation](#cloud-native-computing-foundation). +Backstage is an incubation-stage open source project of the +[Cloud Native Computing Foundation](#cloud-native-computing-foundation). ## Catalog @@ -26,11 +32,19 @@ An organization's portfolio of software products managed in Backstage. ## Cloud Native Computing -A set of technologies that "empower organizations to build and run scalable applications in modern, dynamic environments such as public, private, and hybrid clouds. Containers, service meshes, microservices, immutable infrastructure, and declarative APIs exemplify this approach." ([CNCF Cloud Native Definition v1.0](https://github.com/cncf/toc/blob/main/DEFINITION.md)). +A set of technologies that "empower organizations to build and run scalable +applications in modern, dynamic environments such as public, private, and hybrid +clouds. Containers, service meshes, microservices, immutable infrastructure, and +declarative APIs exemplify this approach." +([CNCF Cloud Native Definition v1.0](https://github.com/cncf/toc/blob/main/DEFINITION.md)). ## Cloud Native Computing Foundation -A foundation dedicated to the promotion and advancement of [Cloud Native Computing](#Cloud-Native-Computing). The mission of the Cloud Native Computing Foundation (CNCF) is "to make cloud native computing ubiquitous" ([CNCF Charter](https://github.com/cncf/foundation/blob/main/charter.md)). +A foundation dedicated to the promotion and advancement of +[Cloud Native Computing](#Cloud-Native-Computing). The mission of the Cloud +Native Computing Foundation (CNCF) is "to make cloud native computing +ubiquitous" +([CNCF Charter](https://github.com/cncf/foundation/blob/main/charter.md)). CNCF is part of the [Linux Foundation](https://www.linuxfoundation.org/). @@ -40,61 +54,82 @@ Cloud Native Computing Foundation. ## Component -A software product that is managed in the Backstage [Software Catalog](#software-catalog). A component can be a service, website, library, data pipeline, or any other piece of software managed as a single project. +A software product that is managed in the Backstage +[Software Catalog](#software-catalog). A component can be a service, website, +library, data pipeline, or any other piece of software managed as a single +project. https://backstage.io/docs/features/software-catalog/system-model ## Contributor -A volunteer who helps to improve an OSS product such as Backstage. This volunteer effort includes coding, testing, technical writing, user support, and other work. A [user role](#user-role). +A volunteer who helps to improve an OSS product such as Backstage. This +volunteer effort includes coding, testing, technical writing, user support, and +other work. A [user role](#user-role). ## Developer -Someone who writes code and develops software. +Someone who writes code and develops software. -A [user role](#user-role) defined as someone who uses a Backstage [app](#app). Might or might not actually be a software developer. +A [user role](#user-role) defined as someone who uses a Backstage [app](#app). +Might or might not actually be a software developer. ## Developer Portal -A centralized system comprising a user interface and database used to facilitate and document all the software projects within an organization. Backstage is both a developer portal and (by virtue of being based on plugins) a platform for creating developer portals. +A centralized system comprising a user interface and database used to facilitate +and document all the software projects within an organization. Backstage is both +a developer portal and (by virtue of being based on plugins) a platform for +creating developer portals. ## Domain -In the Backstage Catalog, a domain is an area that relates systems or entities to a business unit. +In the Backstage Catalog, a domain is an area that relates systems or entities +to a business unit. https://backstage.io/docs/features/software-catalog/system-model ## Entity -What is cataloged in the Backstage Software Catalog. An entity is identified by [kind](#Kind), [namespace](#Namespace), and name. +What is cataloged in the Backstage Software Catalog. An entity is identified by +[kind](#Kind), [namespace](#Namespace), and name. ## Evaluator -Someone who assesses whether Backstage is a suitable solution for their organization. The only [user role](#user-role) with a pre-deployment [use case](#use-case). +Someone who assesses whether Backstage is a suitable solution for their +organization. The only [user role](#user-role) with a pre-deployment +[use case](#use-case). ## Integrator -Someone who develops one or more plugins that enable Backstage to interoperate with another software system. A [user role](#user-role). +Someone who develops one or more plugins that enable Backstage to interoperate +with another software system. A [user role](#user-role). ## Kind -Classification of an [entity](#Entity) in the Backstage Software Catalog, for example *service*, *database*, and *team*. +Classification of an [entity](#Entity) in the Backstage Software Catalog, for +example _service_, _database_, and _team_. ## Kubernetes Plugin -A plugin enabling configuration of Backstage on a Kubernetes cluster. Kubernetes plugin has been promoted to a Backstage core feature. +A plugin enabling configuration of Backstage on a Kubernetes cluster. Kubernetes +plugin has been promoted to a Backstage core feature. ## Mono-Repo -A single repository for a collection of related software projects, such as all projects belonging to an organization. +A single repository for a collection of related software projects, such as all +projects belonging to an organization. ## Namespace -In the Backstage Software Catalog, an optional attribute that can be used to organize [entities](#entity). +In the Backstage Software Catalog, an optional attribute that can be used to +organize [entities](#entity). ## Objective -A high level goal of a [user role](#User-Role) interacting with Backstage. Some goals of the *administrator* user role, for example, are to maintain an instance ("app") of Backstage; to add and update functionality via plugins; and to troubleshoot issues. +A high level goal of a [user role](#User-Role) interacting with Backstage. Some +goals of the _administrator_ user role, for example, are to maintain an instance +("app") of Backstage; to add and update functionality via plugins; and to +troubleshoot issues. ## OSS @@ -106,15 +141,20 @@ Alternative term for a [User Role](#user-role). ## Plugin -A module in Backstage that adds a feature. All functionality in Backstage, even the core features, are implemented as plugins. +A module in Backstage that adds a feature. All functionality in Backstage, even +the core features, are implemented as plugins. ## Procedure -A set of actions that accomplish a goal, usually as part of a [use case](#Use-Case). A procedure can be high-level, containing other procedures, or can be as simple as a single [task](#Task). +A set of actions that accomplish a goal, usually as part of a +[use case](#Use-Case). A procedure can be high-level, containing other +procedures, or can be as simple as a single [task](#Task). ## Resource -In the Backstage Catalog, an [entity](#entity) that represents a piece of physical or virtual infrastructure, for example a database, required by a component. +In the Backstage Catalog, an [entity](#entity) that represents a piece of +physical or virtual infrastructure, for example a database, required by a +component. https://backstage.io/docs/features/software-catalog/system-model @@ -124,21 +164,27 @@ See [User Role](#User-Role). ## Search -A Backstage plugin that provides a framework for searching a Backstage [app](#app), including the [Software Catalog](#Software-Catalog) and [TechDocs](#TechDocs). One of the core features of Backstage. +A Backstage plugin that provides a framework for searching a Backstage +[app](#app), including the [Software Catalog](#Software-Catalog) and +[TechDocs](#TechDocs). One of the core features of Backstage. ## Software Catalog -A centralized system that keeps track of ownership and metadata for any number and type of software [components](#component). A core feature of Backstage. +A centralized system that keeps track of ownership and metadata for any number +and type of software [components](#component). A core feature of Backstage. ## Software Templates -A tool in Backstage with which to create [components](#component) in Backstage. A core feature of Backstage. +A tool in Backstage with which to create [components](#component) in Backstage. +A core feature of Backstage. -A "skeleton" software project created and managed in the Backstage Software Templates tool. +A "skeleton" software project created and managed in the Backstage Software +Templates tool. ## System -In the Backspace Catalog, a system is a collection of [entities](#entity) that cooperate to perform a function. +In the Backspace Catalog, a system is a collection of [entities](#entity) that +cooperate to perform a function. https://backstage.io/docs/features/software-catalog/system-model @@ -148,12 +194,17 @@ A low-level step-by-step [Procedure](#Procedure). ## TechDocs -A documentation solution that manages and generates a technical documentation from Markdown files stored with software component code. A core feature of Backstage. +A documentation solution that manages and generates a technical documentation +from Markdown files stored with software component code. A core feature of +Backstage. ## Use Case -A purpose for which a [user role](#User-Role) interacts with Backstage. Related to [Objective](#objective): An objective is *what* the user wants to do; a use case is *how* the user does it. +A purpose for which a [user role](#User-Role) interacts with Backstage. Related +to [Objective](#objective): An objective is _what_ the user wants to do; a use +case is _how_ the user does it. ## User Role -A class of Backspace user for purposes of analyzing [use cases](#use-case). One of: evaluator; administrator; developer; integrator; and contributor. +A class of Backspace user for purposes of analyzing [use cases](#use-case). One +of: evaluator; administrator; developer; integrator; and contributor. diff --git a/analyses/0008-backstage/backstage-implementation.md b/analyses/0008-backstage/backstage-implementation.md index 0a7ba1d..0bca8cc 100644 --- a/analyses/0008-backstage/backstage-implementation.md +++ b/analyses/0008-backstage/backstage-implementation.md @@ -5,18 +5,31 @@ tags: backstage # Introduction -This document provides actionable suggestions for improving the Backstage technical documentaiton. +This document provides actionable suggestions for improving the Backstage +technical documentaiton. -For an analysis and general discussion of recommendations on Backstage technical documentation, see [backstage-analysis.md][backstage-analysis]]. +For an analysis and general discussion of recommendations on Backstage technical +documentation, see [backstage-analysis.md][backstage-analysis]]. ## Recommendations, requirements, and best practices -Notwithstanding the fact that this analysis measures documentation against CNCF project maturity standards, 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 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. +Notwithstanding the fact that this analysis measures documentation against CNCF +project maturity standards, 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 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: -- Fill gaps in instructional documentation for all stakeholder roles, including project contributors. -- Organize and "signpost" documentation by role and task so that stakeholders can find documentation that supports their roles' activities. +- Fill gaps in instructional documentation for all stakeholder roles, including + project contributors. +- Organize and "signpost" documentation by role and task so that stakeholders + can find documentation that supports their roles' activities. # Definitions @@ -24,203 +37,262 @@ These implementations rely on the following definitions. ## Organization -It is assumed that Backstage is adopted by a medium-to-large *organization* (*org*) made up of a number of *groups*. +It is assumed that Backstage is adopted by a medium-to-large _organization_ +(_org_) made up of a number of _groups_. ## Group -A group is defined by its responsibility for one or more software *products* that are manageable in Backstage. +A group is defined by its responsibility for one or more software _products_ +that are manageable in Backstage. ## Product -Products can include but are not limited to: internal and external toolkits and APIs; components; databases; and web-based and standalone applications. +Products can include but are not limited to: internal and external toolkits and +APIs; components; databases; and web-based and standalone applications. -A group needs 1) visibility into the org's entire corpus of products, and 2) to publicize its own software products to the org. +A group needs 1) visibility into the org's entire corpus of products, and 2) to +publicize its own software products to the org. ## Developer -Members of a group can have various functional and organizational roles, including: software engineer; dev-op; QA engineer; software architect; network engineer; engineering manager; and many others. These implementations refer to a group member generically as a *developer* (*dev*). +Members of a group can have various functional and organizational roles, +including: software engineer; dev-op; QA engineer; software architect; network +engineer; engineering manager; and many others. These implementations refer to a +group member generically as a _developer_ (_dev_). ## Contributor -The org has ties to the Backstage open source software (OSS) project through developers who contribute to the project and who participate in discussions, newsgroups, and other community forums. These OSS participants, regardless of their employer or job function, are called *contributors*. +The org has ties to the Backstage open source software (OSS) project through +developers who contribute to the project and who participate in discussions, +newsgroups, and other community forums. These OSS participants, regardless of +their employer or job function, are called _contributors_. # User Roles -The only distinctions among Backstage users relevant to this implementation discussion are among *user roles*. User roles are defined to organize documentation recommendations. The following table summarizes the user roles that have been identified for that purpose. - -| User Role | Use Cases | -| --- | --- | -| Evaluator | Someone who is trying to decide whether to adopt Backstage into an organization. | -| Administrator | An IT or DevOps professional responsible for standing up and maintaining an organization's instance of Backstage (the *Backstage app*). | -| Developer | The Backstage "end user". A developer, part of a group within an organization. Typically but not always a technical contributor, the developer uses Backstage to learn about and use software components within the org and to publish and document their group's software. | -| Integrator | A developer who modifies an org's Backstage app (typically by writing or modifying a plugin) to add functionality required by the org. This modification might or might not then be contributed back to the Backstage OSS project. | -| Contributor | A developer who supplies a work product (code or documentation, e.g.) to the Backstage open-source project, or who volunteers to participate by providing services (reviews, discussion, or committee membership, e.g.). Much of the contributor documentation is specifically for integrators who contribute plugins or code to the project. | - - -**A note about adoption champions**: A survey of Backstage adopters entitled "Backstage Insights" was undertaken by Spotify. The survey is summarized briefly in [this document][backstage-insights-summary]. Backstage Insights identifies another role, the *Champion*. Due to the complexity and level of commitment needed to adopt Backstage, Backstage Insights deems the champion necessary for an organization to successfully adopt Backstage. Adoption and the champion role are not addressed in the Backstage documentation and are beyond the scope of this analysis. They are important considerations, however, that should be addressed by any organization and for which further exploration and documentation would be valuable. +The only distinctions among Backstage users relevant to this implementation +discussion are among _user roles_. User roles are defined to organize +documentation recommendations. The following table summarizes the user roles +that have been identified for that purpose. + +| User Role | Use Cases | +| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Evaluator | Someone who is trying to decide whether to adopt Backstage into an organization. | +| Administrator | An IT or DevOps professional responsible for standing up and maintaining an organization's instance of Backstage (the _Backstage app_). | +| Developer | The Backstage "end user". A developer, part of a group within an organization. Typically but not always a technical contributor, the developer uses Backstage to learn about and use software components within the org and to publish and document their group's software. | +| Integrator | A developer who modifies an org's Backstage app (typically by writing or modifying a plugin) to add functionality required by the org. This modification might or might not then be contributed back to the Backstage OSS project. | +| Contributor | A developer who supplies a work product (code or documentation, e.g.) to the Backstage open-source project, or who volunteers to participate by providing services (reviews, discussion, or committee membership, e.g.). Much of the contributor documentation is specifically for integrators who contribute plugins or code to the project. | + +**A note about adoption champions**: A survey of Backstage adopters entitled +"Backstage Insights" was undertaken by Spotify. The survey is summarized briefly +in [this document][backstage-insights-summary]. Backstage Insights identifies +another role, the _Champion_. Due to the complexity and level of commitment +needed to adopt Backstage, Backstage Insights deems the champion necessary for +an organization to successfully adopt Backstage. Adoption and the champion role +are not addressed in the Backstage documentation and are beyond the scope of +this analysis. They are important considerations, however, that should be +addressed by any organization and for which further exploration and +documentation would be valuable. # Implementation: Fill gaps in instructional documentation -"Instructional documentation" is a broad category that includes such traditional documentation artifacts as tutorials; getting started guides; procedural recipes or "cookbooks"; runbooks; and how-to guides. We recommend that the project first ensure that basic task documentation is covered, then build out tutorials, cookbooks, and more specialized documentation. +"Instructional documentation" is a broad category that includes such traditional +documentation artifacts as tutorials; getting started guides; procedural recipes +or "cookbooks"; runbooks; and how-to guides. We recommend that the project first +ensure that basic task documentation is covered, then build out tutorials, +cookbooks, and more specialized documentation. Broadly, the recommendation here is to do this: 1. For every [user role][user-roles], define the common use cases for each role. -2. For each use case, develop instructional content, including: - - "Happy path" procedures that can be followed by anyone familiar with the product generally - - examples - - troubleshooting guides - - for new users, tutorials - -There is already some instructional content in the Backstage documentation. In many cases, it is intermingled with conceptual and reference information. A common example of this is in configuration instructions. Many configurations are embodied in YAML files, and the documentation web page for the configuration amounts to an explanation of the contents of a particular config file. In such cases, the page should be rewritten as two or three distinct pages: a step-by-step explanation (not just of the file contents, but where to put it, how to load it, and so on); a configuration reference that exhaustively lists all elements that the file can contain; and if necessary an introduction explaining what the configuration controls. - -The sections below give recommendations for the most important instructional documentation improvements to Backstage for each user role. +2. For each use case, develop instructional content, including: + - "Happy path" procedures that can be followed by anyone familiar with the + product generally + - examples + - troubleshooting guides + - for new users, tutorials + +There is already some instructional content in the Backstage documentation. In +many cases, it is intermingled with conceptual and reference information. A +common example of this is in configuration instructions. Many configurations are +embodied in YAML files, and the documentation web page for the configuration +amounts to an explanation of the contents of a particular config file. In such +cases, the page should be rewritten as two or three distinct pages: a +step-by-step explanation (not just of the file contents, but where to put it, +how to load it, and so on); a configuration reference that exhaustively lists +all elements that the file can contain; and if necessary an introduction +explaining what the configuration controls. + +The sections below give recommendations for the most important instructional +documentation improvements to Backstage for each user role. ## Administrator The following artifacts should be written and made findable for administrators. -1. A server installation and setup guide for administrators. Provide clear, step-by-step instructions for downloading and deploying Backstage to an organization. +1. A server installation and setup guide for administrators. Provide clear, + step-by-step instructions for downloading and deploying Backstage to an + organization. - Instructions can also be provided for installing a local, group-level, or test deployment, but these instructions should be separate and clearly labeled as non-production. + Instructions can also be provided for installing a local, group-level, or + test deployment, but these instructions should be separate and clearly + labeled as non-production. 1. An Administrator Guide, with instructions on how to do such things as: - - Start and stop the Backstage server - - Install and configure Backstage plugins - - Manage the many software dependencies for Backstage and its plugins - - Maintain the Backstage database - - Upgrade and downgrade the Backstage release verison - - Troubleshoot common problems - - Tune server performance + - Start and stop the Backstage server + - Install and configure Backstage plugins + - Manage the many software dependencies for Backstage and its plugins + - Maintain the Backstage database + - Upgrade and downgrade the Backstage release verison + - Troubleshoot common problems + - Tune server performance ## Developer The following artifacts should be written and made findable for developers. -1. A getting started guide for developers. Provide a clear work path that describes how to: - 1. Downloead and install any necessary software components - 1. Integrate Backstage with an existing development environment +1. A getting started guide for developers. Provide a clear work path that + describes how to: -1. A User Guide for developers. Provide clear instructions for these tasks: - - Adding an existing product to Backstage - - Creating a new product in Backstage - - Updating a product in Backstage - - Documenting a product in Backstage - - Deprecating and retiring a product from Backstage - - Searching for a component in Backstage + 1. Downloead and install any necessary software components + 1. Integrate Backstage with an existing development environment +1. A User Guide for developers. Provide clear instructions for these tasks: + - Adding an existing product to Backstage + - Creating a new product in Backstage + - Updating a product in Backstage + - Documenting a product in Backstage + - Deprecating and retiring a product from Backstage + - Searching for a component in Backstage ## Integrator -There are a dizzying array of issues with writing, modifying, and maintaining plugins in Backstage. This is not a detailed recipe for documenting those issues. For integrators, at a high level, a program should be undertaken to: - -1. Organize integrator tasks from most basic and common (write a simple plugin; decide between backend and frontend plugin) to more complex (integrate with external systems; use a proxy; implement authentication). -2. Where possible, using the exisitng documentation as a starting point, write step-by-step procedures for discrete integration tasks (starting with how to write a basic plugin). -3. Organize existing reference and conceptual information (such as API references and architecture discussions) into supporting documentation, referenced from the integration tasks. +There are a dizzying array of issues with writing, modifying, and maintaining +plugins in Backstage. This is not a detailed recipe for documenting those +issues. For integrators, at a high level, a program should be undertaken to: +1. Organize integrator tasks from most basic and common (write a simple plugin; + decide between backend and frontend plugin) to more complex (integrate with + external systems; use a proxy; implement authentication). +2. Where possible, using the exisitng documentation as a starting point, write + step-by-step procedures for discrete integration tasks (starting with how to + write a basic plugin). +3. Organize existing reference and conceptual information (such as API + references and architecture discussions) into supporting documentation, + referenced from the integration tasks. ## Contributor -For a plugin-dependent project like Backstage, it's vital that community members contribute plugins, for two reasons: +For a plugin-dependent project like Backstage, it's vital that community members +contribute plugins, for two reasons: 1. To expand the base functionality of Backstage by covering common use cases -2. To provide complete examples of how plugins are structured, written, and added to the project +2. To provide complete examples of how plugins are structured, written, and + added to the project -Contributor documentation should be in Markdown files in the Backstage GitHub repo and should be limited to how to contribute software to the product. "How to write a plugin" documentation should be included in the website-based doc as described above. +Contributor documentation should be in Markdown files in the Backstage GitHub +repo and should be limited to how to contribute software to the product. "How to +write a plugin" documentation should be included in the website-based doc as +described above. # Organize and "signpost" documentation -Right now different types of documentation (conceptual/architectural; instructional; reference) for different user roles are intermixed throughout the documentation site. +Right now different types of documentation (conceptual/architectural; +instructional; reference) for different user roles are intermixed throughout the +documentation site. -Below is a proposed organization for Backspace by user role, based on a fairly typical documentation set for developer-oriented software. Using exactly this organization is not important. What is important, again, is to document use cases, broken down into tasks, by user role. The documentation should reflect the needs of each user role and be organized such that any user has a clear path to learning the software and becoming proficient as quickly as possible. +Below is a proposed organization for Backspace by user role, based on a fairly +typical documentation set for developer-oriented software. Using exactly this +organization is not important. What is important, again, is to document use +cases, broken down into tasks, by user role. The documentation should reflect +the needs of each user role and be organized such that any user has a clear path +to learning the software and becoming proficient as quickly as possible. -Some documents are used by more than one user role. These docs are listed first under the heading **Common**. +Some documents are used by more than one user role. These docs are listed first +under the heading **Common**. ## Common -| Document | Description | -| --- | --- | +| Document | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Technical overview | A discussion of what the product is and what problems it solves. Ideally, the discussion starts with a summary and provides explanations of increasing depth to address different audiences (evaluator -> developer -> contributor, e.g.). | -| Release notes | Release-specific information, including: new features; performance improvements; bugs and known issues; deprecated features; software dependency changes; and experimental or beta features. | -| Glossary | A dictionary of product-specific terms. Also commonly includes domain- and industry-specific terms that are necessary to understanding the product. | -| Knowledge base | An encyclopedic collection of related background, conceptual, and reference information that doesn't fit elsewhere in the documentation. Similar to a FAQ, but more structured, more searchable and, therefore, more useful. | - +| Release notes | Release-specific information, including: new features; performance improvements; bugs and known issues; deprecated features; software dependency changes; and experimental or beta features. | +| Glossary | A dictionary of product-specific terms. Also commonly includes domain- and industry-specific terms that are necessary to understanding the product. | +| Knowledge base | An encyclopedic collection of related background, conceptual, and reference information that doesn't fit elsewhere in the documentation. Similar to a FAQ, but more structured, more searchable and, therefore, more useful. | ## Evaluator -| Document | Description | -| --- | --- | -| Logo wall | Not a technical document, but a *de rigeur* feature on a product website these days. The logo wall shows at a glance an instantly recognizable selection of organizations that use the product. The logos typically link to testimonials or to the organizations' own websites. | -| Case studies | Another element on a product website that is as much marketing as technical material, a case study nonetheless helps an evaluator decide whether to adopt the product. A handful of well written case studies is sufficient. | +| Document | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Logo wall | Not a technical document, but a _de rigeur_ feature on a product website these days. The logo wall shows at a glance an instantly recognizable selection of organizations that use the product. The logos typically link to testimonials or to the organizations' own websites. | +| Case studies | Another element on a product website that is as much marketing as technical material, a case study nonetheless helps an evaluator decide whether to adopt the product. A handful of well written case studies is sufficient. | ## Administrator -| Document | Description | -| --- | --- | -| CLI reference | An indexed reference to the command-line interface. The Backstage CLI does a wide variety of tasks and is used both the administrator and by developers. | -| Installation and configuration guide | A guide to downloading, installing, and configuring an organization-wide Backstage instance ("app"). | -| Administrator guide | Contains all tasks the administrator needs to maintain the Backstage app: onboarding developers; installing plugins; starting, stopping, upgrading, and troubleshooting the app; using containers; evaluating and tuning server performance. | - +| Document | Description | +| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CLI reference | An indexed reference to the command-line interface. The Backstage CLI does a wide variety of tasks and is used both the administrator and by developers. | +| Installation and configuration guide | A guide to downloading, installing, and configuring an organization-wide Backstage instance ("app"). | +| Administrator guide | Contains all tasks the administrator needs to maintain the Backstage app: onboarding developers; installing plugins; starting, stopping, upgrading, and troubleshooting the app; using containers; evaluating and tuning server performance. | ## Developer -| Document | Description | -| --- | --- | +| Document | Description | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Getting started guide | A document that usually walks a developer through setting up a development environment (for a language or API). In the case of Backstage, this is more of an integration with their existing environment. Nonetheless, this should explain how to configure all the tools the developer needs to begin using Backstage. | -| Developer guide | Contains all tasks that the developer needs to use the Backstage app under normal circumstances: adding products ("catalog population"), modifying, and searching for products; writing documentation; using templates. | -| CLI reference | An indexed reference to the command-line interface. The Backstage CLI does a wide variety of tasks and is used both the administrator and by developers. | -| Tutorials | Tasks that are good candidates for tutorials are difficult, often-used tasks that must be mastered to use the product effectively. Many of these are probably in daily use by developers. | -| Cookbooks | There might be specialized tasks required of developers by an organization that should be documented, especially if they are performed infrequently. | - +| Developer guide | Contains all tasks that the developer needs to use the Backstage app under normal circumstances: adding products ("catalog population"), modifying, and searching for products; writing documentation; using templates. | +| CLI reference | An indexed reference to the command-line interface. The Backstage CLI does a wide variety of tasks and is used both the administrator and by developers. | +| Tutorials | Tasks that are good candidates for tutorials are difficult, often-used tasks that must be mastered to use the product effectively. Many of these are probably in daily use by developers. | +| Cookbooks | There might be specialized tasks required of developers by an organization that should be documented, especially if they are performed infrequently. | ## Integrator -| Document | Description | -| --- | --- | -| Technical overview | Same as the common technical overview, but an integrator will need more detail about the plugin architecture. | -| Cookbooks | The integrator will need to write plugins. This encompasses a large body of task knowledge. The best way to document these is as a collection of tasks or procedures explaining how to complete each task. Even with a comprehensive collection of task documents, some creativity is probably needed by the integrator, since every new plugin by definition is solving a new problem. | - +| Document | Description | +| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Technical overview | Same as the common technical overview, but an integrator will need more detail about the plugin architecture. | +| Cookbooks | The integrator will need to write plugins. This encompasses a large body of task knowledge. The best way to document these is as a collection of tasks or procedures explaining how to complete each task. Even with a comprehensive collection of task documents, some creativity is probably needed by the integrator, since every new plugin by definition is solving a new problem. | ## Contributor -| Document | Description | -| --- | --- | -| GitHub Instructions | Contributing a plugin to Backstage is essentially an exercise in creating and shepherding a pull request through the Backstage community process. This can be documented entirely in GitHub, or it can be a separate section in the Backstage documentation. Regardless, the contributing instructional material should be separate from the integration/"How to write a plugin" material. | - +| Document | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| GitHub Instructions | Contributing a plugin to Backstage is essentially an exercise in creating and shepherding a pull request through the Backstage community process. This can be documented entirely in GitHub, or it can be a separate section in the Backstage documentation. Regardless, the contributing instructional material should be separate from the integration/"How to write a plugin" material. | # Website and documentation infrastructure - ## Single-source repo -Move the Backstage documentation out of the [Backstage repo][backstage-github-project] and into its own repo within the [Backstage project][backstage-backstage]. Write explicit instructions for contributing to documentation and place them in the repo README. - -In the meantime, put references to the documentation contributing and build instructions alongside the project code instructions in the contributor documentation in the Backstage repo. +Move the Backstage documentation out of the [Backstage +repo][backstage-github-project] and into its own repo within the [Backstage +project][backstage-backstage]. Write explicit instructions for contributing to +documentation and place them in the repo README. +In the meantime, put references to the documentation contributing and build +instructions alongside the project code instructions in the contributor +documentation in the Backstage repo. ## Case studies/social proof -Implement a **logo wall** of participating organizations, with links to testimonials or the organizations' websites. Write or solicit a handful of representative case studies and link them from the website. - - +Implement a **logo wall** of participating organizations, with links to +testimonials or the organizations' websites. Write or solicit a handful of +representative case studies and link them from the website. ## SEO, Analytics and site-local search -Add documentation and website custodians to the project maintainer lists in `OWNERS.md` and wherever else project maintainers are documented. - +Add documentation and website custodians to the project maintainer lists in +`OWNERS.md` and wherever else project maintainers are documented. ## Maintenance planning -Add a prominent call for website and documentation maintainers in the project introduction alongside the call for code maintainers. - +Add a prominent call for website and documentation maintainers in the project +introduction alongside the call for code maintainers. ## Accessibility Improve compliance in these areas: + - **Images** should have alternative text. - **Links** should have discernible text. - [backstage-analysis]: ./backstage-analysis.md diff --git a/analyses/0008-backstage/backstage-insights-summary.md b/analyses/0008-backstage/backstage-insights-summary.md index 4fcde8b..88668c7 100644 --- a/analyses/0008-backstage/backstage-insights-summary.md +++ b/analyses/0008-backstage/backstage-insights-summary.md @@ -1,76 +1,127 @@ # Backstage Insights -This document briefly summarizes the research, branded "Backstage Insight," done at Spotify in 2022 to identify ways to drive adoption of Backstage. +This document briefly summarizes the research, branded "Backstage Insight," done +at Spotify in 2022 to identify ways to drive adoption of Backstage. ## Why Backstage Adoption is Hard -Backstage is a complex system that must be adopted universally throughout an organization in order to reap its full benefits. +Backstage is a complex system that must be adopted universally throughout an +organization in order to reap its full benefits. ### Definition of "Adoption" Adoption here means: -1. An organization-wide instance ("app") of Backstage must be installed, run, maintained, and actively updated with new capabilities via plugins; -2. All development groups in the organization must use Backstage to, at the least, catalog their projects. Additional benefits accrue if groups also: - 1. Manage documentation in Backstage; - 2. Use templates in Backstage to create new software artifacts; and - 3. Automate development using Backstage, including integrating Backstage with other development support systems. -3. Backstage must be recognized throughout the organization as the "source of truth" about all software development within the organizaiton. +1. An organization-wide instance ("app") of Backstage must be installed, run, + maintained, and actively updated with new capabilities via plugins; +2. All development groups in the organization must use Backstage to, at the + least, catalog their projects. Additional benefits accrue if groups also: + 1. Manage documentation in Backstage; + 2. Use templates in Backstage to create new software artifacts; and + 3. Automate development using Backstage, including integrating Backstage with + other development support systems. +3. Backstage must be recognized throughout the organization as the "source of + truth" about all software development within the organizaiton. ### Barriers to Adoption -Backstage Insights identifies three types of barriers to adoption: technical, cultural, and combination. +Backstage Insights identifies three types of barriers to adoption: technical, +cultural, and combination. -*Technical* barriers are the effort required for groups to adopt Backstage for software projects, including writing or adapting plugins for features unique to a particular project or group. +_Technical_ barriers are the effort required for groups to adopt Backstage for +software projects, including writing or adapting plugins for features unique to +a particular project or group. -Backstage is a very flexible product with vast potential to adapt to variations in organizational infrastructure and workflows. The flipside is that Backstage is complex, and almost always requires significant investment of talent and resources to implement fully. +Backstage is a very flexible product with vast potential to adapt to variations +in organizational infrastructure and workflows. The flipside is that Backstage +is complex, and almost always requires significant investment of talent and +resources to implement fully. + +_Cultural_ barriers are institutional resistance to adopting Backstage due to: -*Cultural* barriers are institutional resistance to adopting Backstage due to: - Unwillingness to devote resources to adopting and maintaining Backstage; -- Skepticism of the value of Backstage; +- Skepticism of the value of Backstage; - General resistance to change, which is always present in an organization. Cultural barriers are typically more difficult to overcome than technical ones. -*Technical and Cultural* were described as barriers that exhibit a combination of technical and cultural elements. +_Technical and Cultural_ were described as barriers that exhibit a combination +of technical and cultural elements. ## The Backstage Adoption Model -Backstage Insights looked for commonalities in the adoption path of a number of surveyed organizations. The following five-step model was found to be commonly, if not universally, descriptive of the adoption path of the organizations surveyed. - -1. **Problem identification, definition, and alignment**: Identify the problem or problems that require a software solution like Backstage. Recruit the people necessary to pursue a solution. -2. **Finding the right solution**: The identified participants frame the problem and search for solutions. In some cases Backstage had already been identified as a likely or potential solution. -3. **Demo proof of concept**: Set up a limited demo to determine that: Backstage can solve the problem(s); Backstage fits with the organization's infrastructure; resources are available, with the right skill sets, to implement Backstage; Backstage provides value. -4. **Full proof of concept**: Build out functionality and get feedback from users. Gather more rigorous metrics regarding perceived value. This stage is characterized by some hard-to-reverse implementation decisions, so due diligence is advised. -5. **Driving full adoption**: This stage involves committing resources to full adoption. In some cases, expensive mistakes might need to be corrected, despite due diligence in step 4. Resources need to be devoted to shifting the culture to one that values and relies on Backstage. +Backstage Insights looked for commonalities in the adoption path of a number of +surveyed organizations. The following five-step model was found to be commonly, +if not universally, descriptive of the adoption path of the organizations +surveyed. + +1. **Problem identification, definition, and alignment**: Identify the problem + or problems that require a software solution like Backstage. Recruit the + people necessary to pursue a solution. +2. **Finding the right solution**: The identified participants frame the problem + and search for solutions. In some cases Backstage had already been identified + as a likely or potential solution. +3. **Demo proof of concept**: Set up a limited demo to determine that: Backstage + can solve the problem(s); Backstage fits with the organization's + infrastructure; resources are available, with the right skill sets, to + implement Backstage; Backstage provides value. +4. **Full proof of concept**: Build out functionality and get feedback from + users. Gather more rigorous metrics regarding perceived value. This stage is + characterized by some hard-to-reverse implementation decisions, so due + diligence is advised. +5. **Driving full adoption**: This stage involves committing resources to full + adoption. In some cases, expensive mistakes might need to be corrected, + despite due diligence in step 4. Resources need to be devoted to shifting the + culture to one that values and relies on Backstage. ### The Problem To Be Solved: A Note on Desired Outcomes -*Outcomes* are organizational results of adopting Backstage. Desired outcomes are ones that alleviate the problems identified in (1), above. +_Outcomes_ are organizational results of adopting Backstage. Desired outcomes +are ones that alleviate the problems identified in (1), above. -Backstage Insights surveyed both internal (Spotify) Backstage adopters and external organizations to determine the outcomes adopters hoped to achieve. The number one outcome for both internal and external users was to **maintain clear ownership of software**. +Backstage Insights surveyed both internal (Spotify) Backstage adopters and +external organizations to determine the outcomes adopters hoped to achieve. The +number one outcome for both internal and external users was to **maintain clear +ownership of software**. -For external adopters, other top outcomes were consistent with *improving the maturity level of their development practices*, for example standarizing software development practices and increasing collaboration. For internal adopters, other top outcomes were goals that relied on already-mature development practices, for example improving monitoring and tracking costs. The authors hypothesized that this difference was a function of the maturity level of the Backstage implementation at the surveyed organization: already high (for Spotify, where Backstage has been used for years) or low and still developing (for other organizations). +For external adopters, other top outcomes were consistent with _improving the +maturity level of their development practices_, for example standarizing +software development practices and increasing collaboration. For internal +adopters, other top outcomes were goals that relied on already-mature +development practices, for example improving monitoring and tracking costs. The +authors hypothesized that this difference was a function of the maturity level +of the Backstage implementation at the surveyed organization: already high (for +Spotify, where Backstage has been used for years) or low and still developing +(for other organizations). ## Necessity of a Champion -The authors of Backstage Insights were clear that implementing Backstage in an organization requires a *champion*. This champion is dedicated at least part time to evangelizing, implementing, and driving adoption of Backstage throughout the organization. +The authors of Backstage Insights were clear that implementing Backstage in an +organization requires a _champion_. This champion is dedicated at least part +time to evangelizing, implementing, and driving adoption of Backstage throughout +the organization. -Champions varied in their job titles, skill sets, and "everyday" roles. However, some characteristics were common to all Backstage champions: -- Champions were dedicated to changing the status quo to make the professional lives of developers better throughout the organization. +Champions varied in their job titles, skill sets, and "everyday" roles. However, +some characteristics were common to all Backstage champions: + +- Champions were dedicated to changing the status quo to make the professional + lives of developers better throughout the organization. - Champions believed that Backstage was the right platform for positive change. -- Champions were typically leaders (managers or technical leads) before taking on the champion role. -- Champions used a wide variety of technical, leadership, and interpersonal skills to drive the adoption of Backstage. +- Champions were typically leaders (managers or technical leads) before taking + on the champion role. +- Champions used a wide variety of technical, leadership, and interpersonal + skills to drive the adoption of Backstage. ### Champion Job Titles -This is a list of job titles held by Backstage champions in surveyed organizations: - -* DevEx Engineering Manager (2) -* Staff Engineer -* Software Architect -* QA Manager -* Technical PM -* IT Engineering Manager -* Engineering Manager -* Site Reliability Engineer \ No newline at end of file +This is a list of job titles held by Backstage champions in surveyed +organizations: + +- DevEx Engineering Manager (2) +- Staff Engineer +- Software Architect +- QA Manager +- Technical PM +- IT Engineering Manager +- Engineering Manager +- Site Reliability Engineer diff --git a/analyses/0008-backstage/backstage-issues.md b/analyses/0008-backstage/backstage-issues.md index 8015b42..b07ab00 100644 --- a/analyses/0008-backstage/backstage-issues.md +++ b/analyses/0008-backstage/backstage-issues.md @@ -1,10 +1,13 @@ # Backstage umbrella issue -## Overview +## Overview -This is a master list of issues recommended in the Backstage tech doc analysis and implementation plan. +This is a master list of issues recommended in the Backstage tech doc analysis +and implementation plan. -Where possible, issues are self-contained and require a defined level of effort. However, some issues require extended effort; for example, issues that require reorganizing all or most of the technical documentation. +Where possible, issues are self-contained and require a defined level of effort. +However, some issues require extended effort; for example, issues that require +reorganizing all or most of the technical documentation. ## Issues @@ -12,9 +15,13 @@ Where possible, issues are self-contained and require a defined level of effort. - [ ] -Rewrite a basic technical overview. Include: Purpose, features, and benefits of Backstage (without getting too sales-y); core features; basics of architecture including plugins. This is a conceptual document; omit how-to and reference information. Put at top of documentation and link from product landing page. +Rewrite a basic technical overview. Include: Purpose, features, and benefits of +Backstage (without getting too sales-y); core features; basics of architecture +including plugins. This is a conceptual document; omit how-to and reference +information. Put at top of documentation and link from product landing page. -Audience: Evaluators and users who need to find their way around the product without modifying it. +Audience: Evaluators and users who need to find their way around the product +without modifying it. Type: Conceptual @@ -22,9 +29,13 @@ Type: Conceptual - [ ] -This is an in-depth overview of the Backstage product, probably in several web pages. Include a conceptual overview of the frontend, the backend, and plugin-based architecture. Briefly describe APIs (with links to API references, but no syntax reference here). +This is an in-depth overview of the Backstage product, probably in several web +pages. Include a conceptual overview of the frontend, the backend, and +plugin-based architecture. Briefly describe APIs (with links to API references, +but no syntax reference here). -Audience: Integrators and contributors. Possibly admins and developers who need to configure plugins. +Audience: Integrators and contributors. Possibly admins and developers who need +to configure plugins. Type: Conceptual @@ -32,7 +43,10 @@ Type: Conceptual - [ ] -Rewrite the standalone installation. Make clear that this is a non-production install that a user might want to do for one of several reasons: demo, proof of concept, development environment, etc. Organize under *Getting Started* in the doc TOC. +Rewrite the standalone installation. Make clear that this is a non-production +install that a user might want to do for one of several reasons: demo, proof of +concept, development environment, etc. Organize under _Getting Started_ in the +doc TOC. Audience: Developer, Admin @@ -42,7 +56,12 @@ Type: Task - [ ] -Reorganize and rewrite the production-oriented installations, gathered here in Getting Started. Start with an introduction to help select an install configuration. Include a section for every install configuration: Kubernetes; Heroku; distributed plugins (as in "New Backend" in existing doc); any others. End with *Next Steps* section with links to configuration, setup, administration docs. Organize under *Getting Started* in the doc TOC. +Reorganize and rewrite the production-oriented installations, gathered here in +Getting Started. Start with an introduction to help select an install +configuration. Include a section for every install configuration: Kubernetes; +Heroku; distributed plugins (as in "New Backend" in existing doc); any others. +End with _Next Steps_ section with links to configuration, setup, administration +docs. Organize under _Getting Started_ in the doc TOC. Audience: Admin @@ -52,7 +71,11 @@ Type: Task - [ ] -Write step-by-step instructions to start, restart, check status, and stop a production Backstage server. Include a separate procedure for every install configuration (Kubernetes, standalone, etc.). Add procedures for any other server-related actions needed by the admin. Can also include sections on tuning server performance in each case. Organize under *Admin Guide* in the doc TOC. +Write step-by-step instructions to start, restart, check status, and stop a +production Backstage server. Include a separate procedure for every install +configuration (Kubernetes, standalone, etc.). Add procedures for any other +server-related actions needed by the admin. Can also include sections on tuning +server performance in each case. Organize under _Admin Guide_ in the doc TOC. Audience: Admin @@ -62,7 +85,9 @@ Type: Task - [ ] -Write step-by-step instructions for installing and configuring a plugin. Include how to test the plugin if there's a generic way to do that. Organize under *Admin Guide* in the doc TOC. +Write step-by-step instructions for installing and configuring a plugin. Include +how to test the plugin if there's a generic way to do that. Organize under +_Admin Guide_ in the doc TOC. Audience: Admin @@ -72,7 +97,9 @@ Type: Task - [ ] -Write a guide to upgrade or downgrade the version of Backstage. Include instructions on how to check and update dependencies. Organize under *Admin Guide* in the doc TOC. +Write a guide to upgrade or downgrade the version of Backstage. Include +instructions on how to check and update dependencies. Organize under _Admin +Guide_ in the doc TOC. Audience: Admin @@ -82,7 +109,9 @@ Type: Task - [ ] -Write procedures for setting up and maintaining a database for Backstage. Include a separate procedure for every DBMS that can be used. Organize under *Admin Guide* in the doc TOC. +Write procedures for setting up and maintaining a database for Backstage. +Include a separate procedure for every DBMS that can be used. Organize under +_Admin Guide_ in the doc TOC. Audience: Admin @@ -92,7 +121,11 @@ Type: Task - [ ] -Write a short guide for developers to get started with an existing production Backstage app (or a standalone server in a development environment). Include any tools that need to be installed and how to access the UI. Include a *Next Steps* section that points to the Developer User Guide. Organize under *Getting Started* in the doc TOC. +Write a short guide for developers to get started with an existing production +Backstage app (or a standalone server in a development environment). Include any +tools that need to be installed and how to access the UI. Include a _Next Steps_ +section that points to the Developer User Guide. Organize under _Getting +Started_ in the doc TOC. Audience: Developer @@ -102,17 +135,27 @@ Type: Task - [ ] -Write a guide to managing a product in Backstage. Topics include adding, updating, and releasing a a product. This might need to be expanded based on type of product and for different code repo and CI/CD systems, but this should provide an entry point outlining tasks that are common to all products and environments, with links to more specific instructions. Organize under *Developer* in the doc TOC. +Write a guide to managing a product in Backstage. Topics include adding, +updating, and releasing a a product. This might need to be expanded based on +type of product and for different code repo and CI/CD systems, but this should +provide an entry point outlining tasks that are common to all products and +environments, with links to more specific instructions. Organize under +_Developer_ in the doc TOC. Audience: Developer Type: Task -### Write a guide to the UI. +### Write a guide to the UI. - [ ] -Write a guide to using the UI to find and explore products. Currently there is no documentation to using the UI. A complete guide to the UI is probably unnecessary, but the tasks that represent the core value prop should be documented, including how to search for and examine products – especially services and APIs meant to be usable by other developers. Organize under *Developer* in the doc TOC. +Write a guide to using the UI to find and explore products. Currently there is +no documentation to using the UI. A complete guide to the UI is probably +unnecessary, but the tasks that represent the core value prop should be +documented, including how to search for and examine products – especially +services and APIs meant to be usable by other developers. Organize under +_Developer_ in the doc TOC. Audience: Developer @@ -122,7 +165,11 @@ Type: Task - [ ] -Write a guide to developing a basic plugin. Include step-by-step instructions to creating and deploying a bare-bones plugin. This should provide a jumping-off point to other integrator tasks of an increasingly advanced nature, such as proxies, security, and integrating with specific systems. Organize under *Integrator* or *Getting Started* (or both) in the doc TOC. +Write a guide to developing a basic plugin. Include step-by-step instructions to +creating and deploying a bare-bones plugin. This should provide a jumping-off +point to other integrator tasks of an increasingly advanced nature, such as +proxies, security, and integrating with specific systems. Organize under +_Integrator_ or _Getting Started_ (or both) in the doc TOC. Audience: Integrator @@ -132,7 +179,9 @@ Type: Task - [ ] -Reorganize the documentation table of contents around user roles. A suggested high-level organization: +Reorganize the documentation table of contents around user roles. A suggested +high-level organization: + - Introduction and technical overview - Getting started (subsections organized by user role) - Administrator Guide @@ -140,13 +189,22 @@ Reorganize the documentation table of contents around user roles. A suggested hi - Integrator Guide - Reference -In practice, this will have to be done gradually as material is reorganized and rewritten within the documentation set. Much of this reorganization can be done in the form of new sections associated with other Backstage documentation issues. For example, the Getting Started TOC entry already exists; it can be reorganized as the Admin and Developer "getting started" sections are completed. Admin and Developer guides can be added with some rewritten task-based documentation. They can contain pointers to existing documentation pages until those pages are replaced or rewritten. +In practice, this will have to be done gradually as material is reorganized and +rewritten within the documentation set. Much of this reorganization can be done +in the form of new sections associated with other Backstage documentation +issues. For example, the Getting Started TOC entry already exists; it can be +reorganized as the Admin and Developer "getting started" sections are completed. +Admin and Developer guides can be added with some rewritten task-based +documentation. They can contain pointers to existing documentation pages until +those pages are replaced or rewritten. ### Compile glossary - [ ] -Compile a comprehensive Backstage glossary using definitions already found in the documentation plus new definitions. Many proposed entries were written while compiling the Backstage doc analysis. +Compile a comprehensive Backstage glossary using definitions already found in +the documentation plus new definitions. Many proposed entries were written while +compiling the Backstage doc analysis. Audience: All @@ -156,7 +214,9 @@ Type: Reference - [ ] -Replace the FAQ with an indexed knowledge base. The knowledge base is an encyclopedic collection of related background, conceptual, and reference information that doesn't fit elsewhere in the documentation. +Replace the FAQ with an indexed knowledge base. The knowledge base is an +encyclopedic collection of related background, conceptual, and reference +information that doesn't fit elsewhere in the documentation. Audience: All @@ -166,7 +226,8 @@ Type: Conceptual - [ ] -Create a logo wall containing a recognizable selection of organizations that use the product. Link each logo to the organization's website. +Create a logo wall containing a recognizable selection of organizations that use +the product. Link each logo to the organization's website. Audience: Evaluator @@ -176,7 +237,8 @@ Type: Marketing - [ ] -Write a representative selection of case studies. Link from the product main page. +Write a representative selection of case studies. Link from the product main +page. Audience: Evaluator @@ -186,9 +248,13 @@ Type: Marketing, conceptual - [ ] -Move the Backstage documentation out of the Backstage repo and into its own repo within the Backstage project. Write explicit instructions for contributing to documentation and place them in the repo README. +Move the Backstage documentation out of the Backstage repo and into its own repo +within the Backstage project. Write explicit instructions for contributing to +documentation and place them in the repo README. -In the meantime, put references to the documentation contributing and build instructions alongside the project code instructions in the contributor documentation in the Backstage repo. +In the meantime, put references to the documentation contributing and build +instructions alongside the project code instructions in the contributor +documentation in the Backstage repo. ### Website: Accessibility diff --git a/analyses/0008-backstage/user-roles.md b/analyses/0008-backstage/user-roles.md index 06e2be7..611aa55 100644 --- a/analyses/0008-backstage/user-roles.md +++ b/analyses/0008-backstage/user-roles.md @@ -1,31 +1,50 @@ # Backstage User Roles for Doc -This document provides recommendations for user roles, or personas, for Backstage. The goal here is to identify a working set of distinct user roles around which to organize the Backstage documentation. +This document provides recommendations for user roles, or personas, for +Backstage. The goal here is to identify a working set of distinct user roles +around which to organize the Backstage documentation. -The documentation should ultimately be task-oriented, with tasks organized around users and their objectives. A process for creating this type of documentation set is under development in the CDCF Tech Doc GitHub project. +The documentation should ultimately be task-oriented, with tasks organized +around users and their objectives. A process for creating this type of +documentation set is under development in the CDCF Tech Doc GitHub project. ## Summary of Proposed User Roles -The following table summarizes Backstage user roles proposed by the Backstage OSS community\*. The roles assume the following: - -- An organization has software objectives that cannot be met without a centralized solution, and has resolved to commit resources to solving those problems. -- The organization adopts Backstage, setting up a single, central Backstage server instance ("app"). -- The organization contains many development groups. These groups can be organized in any manner, but this document assumes a flat organization of small development groups. -- "Development group" refers to any group that produces a software product manageable in Backstage, including but not limited to internal and external toolkits and APIs; components; databases; and web-based and standalone applications. -- The organization has ties to the Backstage open source software project, specifically: - - One or more engineers who contribute to the project. - - Developer users who ask questions and participate in discussions, newsgroups, and other community forums. +The following table summarizes Backstage user roles proposed by the Backstage +OSS community\*. The roles assume the following: + +- An organization has software objectives that cannot be met without a + centralized solution, and has resolved to commit resources to solving those + problems. +- The organization adopts Backstage, setting up a single, central Backstage + server instance ("app"). +- The organization contains many development groups. These groups can be + organized in any manner, but this document assumes a flat organization of + small development groups. +- "Development group" refers to any group that produces a software product + manageable in Backstage, including but not limited to internal and external + toolkits and APIs; components; databases; and web-based and standalone + applications. +- The organization has ties to the Backstage open source software project, + specifically: + - One or more engineers who contribute to the project. + - Developer users who ask questions and participate in discussions, + newsgroups, and other community forums. \*Ultimately. This document is a work in progress to be revised by consensus. -| User Role | Org Level | Description | -| --------- | --- | ----------- | -| Champion | Organization | A combination evangelist/implementer/coordinator dedicated to driving adoption of Backstage at an organization. The champion is vital to removing barriers to developer adoption by, among other things, making the developer experience a delight and by demonstrating Backstage's value. | -| Administrator | Organization | An IT or DevOps professional responsible for setting up and maintaining an organization's Backstage app. The administrator might or might not also be the Backstage champion. | -| Internal Integrator | Group or Org | An engineer within an organization who creates or modifies the org's Backstage app (typically by writing or modifying a plugin) to add functionality required by the org. This modification might or might not then be contributed back to the Backstage OSS project. | -| Group maintainer | Group | A member of a software group responsible for keeping the group's Backstage entries up to date. | -| End-user developer | Group | The "bread and butter" user of Backstage, an end-user developer is part of a group within an organization that uses Backstage to both learn about and use software components within the org and to publish and document its own software. | -| Contributor developer | Backstage OSS | A contributor to the Backstage open-source project. Many if not most contributors develop plugins to extend the functionality and integration capabilities of Backstage. | -| Integrator | Backstage OSS | A contributing developer who develops a plugin that enables Backstage to interoperate with another system. | - -These roles might overlap; or, in some cases, especially in small organizations, the same person might fill two or more roles. For example, the champion might be the Backstage administrator, and/or might also be responsible for internal integration projects. Or, an integration project might fall to an end-user developer in a group that requires functionality not yet available in Backstage. +| User Role | Org Level | Description | +| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Champion | Organization | A combination evangelist/implementer/coordinator dedicated to driving adoption of Backstage at an organization. The champion is vital to removing barriers to developer adoption by, among other things, making the developer experience a delight and by demonstrating Backstage's value. | +| Administrator | Organization | An IT or DevOps professional responsible for setting up and maintaining an organization's Backstage app. The administrator might or might not also be the Backstage champion. | +| Internal Integrator | Group or Org | An engineer within an organization who creates or modifies the org's Backstage app (typically by writing or modifying a plugin) to add functionality required by the org. This modification might or might not then be contributed back to the Backstage OSS project. | +| Group maintainer | Group | A member of a software group responsible for keeping the group's Backstage entries up to date. | +| End-user developer | Group | The "bread and butter" user of Backstage, an end-user developer is part of a group within an organization that uses Backstage to both learn about and use software components within the org and to publish and document its own software. | +| Contributor developer | Backstage OSS | A contributor to the Backstage open-source project. Many if not most contributors develop plugins to extend the functionality and integration capabilities of Backstage. | +| Integrator | Backstage OSS | A contributing developer who develops a plugin that enables Backstage to interoperate with another system. | + +These roles might overlap; or, in some cases, especially in small organizations, +the same person might fill two or more roles. For example, the champion might be +the Backstage administrator, and/or might also be responsible for internal +integration projects. Or, an integration project might fall to an end-user +developer in a group that requires functionality not yet available in Backstage. diff --git a/analyses/0009-in-toto/README.md b/analyses/0009-in-toto/README.md index 8d24b6b..5367d5f 100644 --- a/analyses/0009-in-toto/README.md +++ b/analyses/0009-in-toto/README.md @@ -1,26 +1,42 @@ # README -These documents are intended to recommend a direction for the ongoing development of technical documentation for the in-toto open source software (OSS) project. This effort 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. +These documents are intended to recommend a direction for the ongoing +development of technical documentation for the in-toto open source software +(OSS) project. This effort 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 [CNCF-techdocs](https://github.com/cncf/techdocs) group is developing a +process aimed at assisting cloud-native open-source projects with their +documentation efforts. The process has three steps: -The [CNCF-techdocs](https://github.com/cncf/techdocs) group is developing a process aimed at assisting cloud-native open-source projects with their documentation efforts. The process has three steps: 1. Analysis - A professional technical writer surveys the current project documentation and website, and analyzes it with respect to CNCF criteria for completeness, discoverability, and usability. - + A professional technical writer surveys the current project documentation and + website, and analyzes it with respect to CNCF criteria for completeness, + discoverability, and usability. + 2. Recommendations - The analyst makes general recommendations for organizing, extending, and improving documentation to meet CNCF standards appropriate to the project's maturity status. - + The analyst makes general recommendations for organizing, extending, and + improving documentation to meet CNCF standards appropriate to the project's + maturity status. + 3. Doc Plan - The analyst outlines a program of key improvements intended to provide the largest return on investment. -This is an actionable plan for doc improvement, with specific implementation recommendations suitable to the open-source development environment. + The analyst outlines a program of key improvements intended to provide the + largest return on investment. This is an actionable plan for doc improvement, + with specific implementation recommendations suitable to the open-source + development environment. ## Results for in-toto -The analysis and recommendations for the in-toto project documentation are presented in these files: +The analysis and recommendations for the in-toto project documentation are +presented in these files: -- [Survey of existing documentation](./survey-of-existing-doc.md) (as of September 2023) +- [Survey of existing documentation](./survey-of-existing-doc.md) (as of + September 2023) - [Analysis](./in-toto-analysis.md) - [Recommendations and implementation](./in-toto-implementation.md) - [Proposed actionable issues](./in-toto-doc-issues.md) diff --git a/analyses/0009-in-toto/in-toto-analysis.md b/analyses/0009-in-toto/in-toto-analysis.md index 95805f4..dd3d0b5 100644 --- a/analyses/0009-in-toto/in-toto-analysis.md +++ b/analyses/0009-in-toto/in-toto-analysis.md @@ -1,36 +1,62 @@ # Analysis of Existing Documentation -This document characterizes the effectiveness and completeness of the in-toto open source software (OSS) project's documentation and website as of September 2023. Documentation is analyzed with respect to CNCF criteria for completeness, discoverability, and usability. -The analysis forms the basis for the recommendations and doc plan presented in the companion [Implementation document](./in-toto-implementation.md). +This document characterizes the effectiveness and completeness of the in-toto +open source software (OSS) project's documentation and website as of +September 2023. Documentation is analyzed with respect to CNCF criteria for +completeness, discoverability, and usability. + +The analysis forms the basis for the recommendations and doc plan presented in +the companion [Implementation document](./in-toto-implementation.md). ## Scope of analysis -The documentation discussed here includes the contents of the website at https://in-toto.io and https://in-toto.readthedocs.io/, the [in-toto Specification](https://github.com/in-toto/docs/tree/master/in-toto-spec.md), and the documentation for contributors and users in the various GitHub repositories at https://github.com/in-toto. See [Survey of existing documentation](./survey-of-existing-doc.md). + +The documentation discussed here includes the contents of the website at +https://in-toto.io and https://in-toto.readthedocs.io/, the +[in-toto Specification](https://github.com/in-toto/docs/tree/master/in-toto-spec.md), +and the documentation for contributors and users in the various GitHub +repositories at https://github.com/in-toto. See +[Survey of existing documentation](./survey-of-existing-doc.md). ### How this document is organized -Recommendations are based on an analysis of the existing documentation. The analysis is divided into three sections that represent three major areas of concern: +Recommendations are based on an analysis of the existing documentation. The +analysis is divided into three sections that represent three major areas of +concern: -- User documentation: concerns documentation for users of the in-toto framework; aimed at people who intend to implement or integrate the framework locally, and people who intend to use the local implementation. +- User documentation: concerns documentation for users of the in-toto framework; + aimed at people who intend to implement or integrate the framework locally, + and people who intend to use the local implementation. -- Contributor documentation: concerns documentation for new and existing contributors to the project. +- Contributor documentation: concerns documentation for new and existing + contributors to the project. -- Website: concerns the mechanics of publishing the documentation; includes branding, website structure, and maintainability. +- Website: concerns the mechanics of publishing the documentation; includes + branding, website structure, and maintainability. -Each section begins with a summary of current status based on a rubric with appropriate criteria for the section, then proceeds to: +Each section begins with a summary of current status 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 in-toto users achieve their goals. +- Comments: observations about the existing documentation, with a focus on how + it does or does not help in-toto users achieve their goals. -- Recommendations: suggested changes that would improve the effectiveness of the documentation in a specific area. +- Recommendations: suggested changes that would improve the effectiveness of the + documentation in a specific area. -The companion [Implementation document](./in-toto-implementation.md) organizes the recommendations into concrete actions that can be implemented by project contributors. +The companion [Implementation document](./in-toto-implementation.md) organizes +the recommendations into concrete actions that can be implemented by project +contributors. -The intention is to drill down to specific, achievable documentation tasks that can be completed in constrained blocks of time. +The intention is to drill down to specific, achievable documentation tasks that +can be completed in constrained blocks of time. -Ultimately, the implementation items should be tracked as a series of Github documentation issues that can be undertaken by contributors. +Ultimately, the implementation items should be tracked as a series of Github +documentation issues that can be undertaken by contributors. ## How to use this document -Readers interested only in actionable improvements can skip to the [implementation recommendations](./in-toto-implementation.md). For more context, read the recommendations for each of the three areas of analysis: +Readers interested only in actionable improvements can skip to the +[implementation recommendations](./in-toto-implementation.md). For more context, +read the recommendations for each of the three areas of analysis: - [Project documentation recommendations](./assessments#recommendations) @@ -38,7 +64,8 @@ Readers interested only in actionable improvements can skip to the [implementati - [Website recommendations](./assessments#recommendations-2) -Readers interested in the current state of the documentation and the reasoning behind the recommendations should start with the analyses: +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should start with the analyses: - [Project documentation](./assessments#project-documentation-analysis) @@ -51,13 +78,13 @@ Readers interested in the current state of the documentation and the reasoning b ## Project documentation analysis | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Information architecture | | | x | | | -| New user content | | | x | | | -| Content maintainability | | | x | | | -| Content creation processes | | | x | | | +| -------------------------- | --- | --- | --- | --- | --- | +| Information architecture | | | x | | | +| New user content | | | x | | | +| Content maintainability | | | x | | | +| Content creation processes | | | x | | | -Scale: +Scale: - 1 = (Is not present or requires significant work) - 3 = (Is present, but needs work) @@ -65,75 +92,126 @@ Scale: ### Comments -**Information Architecture**: - -Content is well-written, clear, and fairly complete, but scattered among the Specification, GitHub READMEs, and read-the-docs. -Almost all doc content is in GitHub (in README files, the Specification, or comments in demos). -The purpose of specific GitHub repos and folders is not obvious and doesn't seem to be described anywhere. This makes it difficult to find doc and doc sources. -Repo naming and organization need to be reconsidered. - - The docs repo contains the spec, which is a very good spec, but is also apparently standing in for user documentation. The README for this repo does not (despite the name) say anything explicitly about documentation, or explain what is supposed to go in the repo. - - The in-toto/in-toto/in-toto folder contains the Python reference implementation, and the doc subfolder contains the source for the generated API Reference docs for that implementation. This organization and naming is unhelpful and confusing. There needs to be a policy for how different implementations are located, named, and documented. -- Much documentation, addressed to different audiences, is in READMEs throughout the many repos. It is often difficult to figure out the purpose of a given repo and the intended users. +**Information Architecture**: + +Content is well-written, clear, and fairly complete, but scattered among the +Specification, GitHub READMEs, and read-the-docs. Almost all doc content is in +GitHub (in README files, the Specification, or comments in demos). The purpose +of specific GitHub repos and folders is not obvious and doesn't seem to be +described anywhere. This makes it difficult to find doc and doc sources. Repo +naming and organization need to be reconsidered. + +- The docs repo contains the spec, which is a very good spec, but is also + apparently standing in for user documentation. The README for this repo does + not (despite the name) say anything explicitly about documentation, or explain + what is supposed to go in the repo. +- The in-toto/in-toto/in-toto folder contains the Python reference + implementation, and the doc subfolder contains the source for the generated + API Reference docs for that implementation. This organization and naming is + unhelpful and confusing. There needs to be a policy for how different + implementations are located, named, and documented. +- Much documentation, addressed to different audiences, is in READMEs throughout + the many repos. It is often difficult to figure out the purpose of a given + repo and the intended users. **New user content**: -There are a lot of of good intro topics and get-started demos, but they are not immediately discoverable or identifiable. -- The Specification has an excellent high-level overview that includes the expected workflow, identifies user roles, and provides a Glossary. It would be very helpful for new users to separate out and clearly label these components. -- A decent Getting Started guide for beginners is currently contained in the README for the main repo.The Get Started menu on the home page currently points to demos and the spec, but not to this content. - -**Content maintainability**: +There are a lot of of good intro topics and get-started demos, but they are not +immediately discoverable or identifiable. + +- The Specification has an excellent high-level overview that includes the + expected workflow, identifies user roles, and provides a Glossary. It would be + very helpful for new users to separate out and clearly label these components. +- A decent Getting Started guide for beginners is currently contained in the + README for the main repo.The Get Started menu on the home page currently + points to demos and the spec, but not to this content. -The scattered docs make specific info hard to find, and lead to duplication that can complicate maintenance. -High-level overviews are provided in several places, and mostly embedded in other documents. These are hard to compare and keep in sync. +**Content maintainability**: -**Content creation processes**: +The scattered docs make specific info hard to find, and lead to duplication that +can complicate maintenance. High-level overviews are provided in several places, +and mostly embedded in other documents. These are hard to compare and keep in +sync. -The Contributing and Governance files do not mention changes or additions to documentation as potential areas of contribution. +**Content creation processes**: + +The Contributing and Governance files do not mention changes or additions to +documentation as potential areas of contribution. ### Recommendations **Information Architecture** -A combination of renaming and restructuring can resolve some of the discoverability problems. A comprehensive repo map and documentation guide can do more. - - Move most of the documentation into the website. - - Create a Documentation Home Page and link it to a Docs or Documentation button on the in-toto home page. - - On the Doc home page itself, provide an index or TOC that shows the organizational structure of the documentation, with a link to and short description of every section. - -The Read-the-Docs (RTD) site, https://in-toto.readthedocs.io/ currently has the reference docs for the Python reference implementation. -If you use the same tool to create web pages for the rest of the documentation, that URL can be repurposed as the Doc home page (and eliminate a too-general URL for the reference implementation). -The current Python reference doc can be moved into a "Reference Documentation" subsection, whose home page can also include or point to references for other implementations. -Include a map to the GitHub repos, with links and descriptions of the intended usage. Revisit this after any restructuring and renaming of repos. +A combination of renaming and restructuring can resolve some of the +discoverability problems. A comprehensive repo map and documentation guide can +do more. + +- Move most of the documentation into the website. +- Create a Documentation Home Page and link it to a Docs or Documentation button + on the in-toto home page. +- On the Doc home page itself, provide an index or TOC that shows the + organizational structure of the documentation, with a link to and short + description of every section. + +The Read-the-Docs (RTD) site, https://in-toto.readthedocs.io/ currently has the +reference docs for the Python reference implementation. If you use the same tool +to create web pages for the rest of the documentation, that URL can be +repurposed as the Doc home page (and eliminate a too-general URL for the +reference implementation). The current Python reference doc can be moved into a +"Reference Documentation" subsection, whose home page can also include or point +to references for other implementations. Include a map to the GitHub repos, with +links and descriptions of the intended usage. Revisit this after any +restructuring and renaming of repos. **New user content** -Extract information for the Specification to create a high-level overview aimed explicitly at evaluators and new users that describes the expected workflow, identifies user roles, and provides a Glossary. Label those sections or put them on separate pages to that they can be more easily found. -Turn the README for the main repo content into a Get Started document and make that the first menu item in the Get Started menu (wherever that ends up). +Extract information for the Specification to create a high-level overview aimed +explicitly at evaluators and new users that describes the expected workflow, +identifies user roles, and provides a Glossary. Label those sections or put them +on separate pages to that they can be more easily found. Turn the README for the +main repo content into a Get Started document and make that the first menu item +in the Get Started menu (wherever that ends up). **Content maintainability** -Almost all doc content is in GitHub (in README files, the Specification, or comments in demos). -Most of it should be exposed as indexed documents on the website to make it versionable, editable, and localizable. - - Move most of the documentation into read-the-docs (RTD) so that it can properly indexed and maintained. - - Repurpose the README files in GitHub to provide a quick summary of what is in the repo, and link to the Doc home page (or directly into a relevant section of the web doc) for detailed information. - - Offer a single overview page with increasing layers of depth to help different audiences (evaluators, new users, experienced users, contributors). -This will consolidate overviews currently found in several places and make revising and maintaining the overviews easier. A single source for some of the text would help. +Almost all doc content is in GitHub (in README files, the Specification, or +comments in demos). Most of it should be exposed as indexed documents on the +website to make it versionable, editable, and localizable. + +- Move most of the documentation into read-the-docs (RTD) so that it can + properly indexed and maintained. +- Repurpose the README files in GitHub to provide a quick summary of what is in + the repo, and link to the Doc home page (or directly into a relevant section + of the web doc) for detailed information. +- Offer a single overview page with increasing layers of depth to help different + audiences (evaluators, new users, experienced users, contributors). This will + consolidate overviews currently found in several places and make revising and + maintaining the overviews easier. A single source for some of the text would + help. **Content creation processes** -Material explicitly addressed to documentation contributions and standards should be added and made accessible from the top-level doc roadmap as well as from the existing contributor pages. +Material explicitly addressed to documentation contributions and standards +should be added and made accessible from the top-level doc roadmap as well as +from the existing contributor pages. + - Procedures for creating and maintaining docs need to be documented. - - The process should include a policy for where reference docs live in the repo structure and how docs for different implementations are distinguished and identified. -- Policy and procedures for documenting implementations need to be decided and published for contributors. - - Reference documentation for additional implementations should be actively solicited from the contributor community. + - The process should include a policy for where reference docs live in the + repo structure and how docs for different implementations are distinguished + and identified. +- Policy and procedures for documenting implementations need to be decided and + published for contributors. + - Reference documentation for additional implementations should be actively + solicited from the contributor community. ## Contributor documentation analysis | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Communication methods documented | | | | x | | -| Beginner friendly issue backlog | | x | | | | -| “New contributor” getting started content | | x | | | | -| Project governance documentation | | | | x | | +| ----------------------------------------- | --- | --- | --- | --- | --- | +| Communication methods documented | | | | x | | +| Beginner friendly issue backlog | | x | | | | +| “New contributor” getting started content | | x | | | | +| Project governance documentation | | | | x | | Scale: @@ -143,63 +221,82 @@ Scale: ### Comments -**Communication methods documented**: A Contact channels list is available from home page under Community > Contact. +**Communication methods documented**: A Contact channels list is available from +home page under Community > Contact. -**Beginner friendly issue backlog**: A "Good First Issue" label is available and used for PRs for specific implementations. Not in much general use. +**Beginner friendly issue backlog**: A "Good First Issue" label is available and +used for PRs for specific implementations. Not in much general use. -**“New contributor” getting started content**: The Community README points to "Good First Issues" list for specific repos. I couldn’t find explicit instructions for new contributors, or any first issues for other kinds of contribution (such as docs). +**“New contributor” getting started content**: The Community README points to +"Good First Issues" list for specific repos. I couldn’t find explicit +instructions for new contributors, or any first issues for other kinds of +contribution (such as docs). -**Project governance documentation**: Clearly described and discoverable on GOVERNANCE page. +**Project governance documentation**: Clearly described and discoverable on +GOVERNANCE page. ### Recommendations **Communication methods documented** - Since most of the documentation is currently in GitHub, rather than on the web site, the Contact channels list could be usefully added to the READMEs for the main and community repos. - Contact info, which is unlikely to change, can be linked from a clearly labeled section of the new Docs website. +Since most of the documentation is currently in GitHub, rather than on the web +site, the Contact channels list could be usefully added to the READMEs for the +main and community repos. Contact info, which is unlikely to change, can be +linked from a clearly labeled section of the new Docs website. **Beginner friendly issue backlog** - Documentation would benefit from a backlog of issues labeled with both "Good First Issue" and "Documentation". - Use of these labels would have to be strongly encouraged in getting-started content for contributors. +Documentation would benefit from a backlog of issues labeled with both "Good +First Issue" and "Documentation". Use of these labels would have to be strongly +encouraged in getting-started content for contributors. -CNCF has developed a new tool, CLOTributor, that can help orient new contributors: see https://clotributor.dev/ and https://github.com/cncf/clotributor. +CNCF has developed a new tool, CLOTributor, that can help orient new +contributors: see https://clotributor.dev/ and +https://github.com/cncf/clotributor. - One of its goals is to surface interesting opportunities for potential contributors to Cloud Native projects, allowing them to find those that suit their skills and interests best. - To achieve this, CLOTributor scans periodically hundreds of repositories, indexing issues that match certain criteria: +One of its goals is to surface interesting opportunities for potential +contributors to Cloud Native projects, allowing them to find those that suit +their skills and interests best. To achieve this, CLOTributor scans periodically +hundreds of repositories, indexing issues that match certain criteria: - Contain the help wanted label - Their state is OPEN - They are unassigned - Updated within the last year - + **“New contributor” getting started content** - The CONTRIBUTING page should have much more explicit instructions for how to submit PRs and how to find good first issues. +The CONTRIBUTING page should have much more explicit instructions for how to +submit PRs and how to find good first issues. **Project governance documentation** -- The governance policies call out the Contributors and Maintainers project roles, and mention that doc changes require one maintainer approval. -They should also define Doc Contributors as a role, with information on documentation standards, and who should review such changes. -- The CONTRIBUTING page should explicitly mention documentation changes as distinct from "making code changes" as an area of contribution. -- The CONTRIBUTING page needs explicit information for how to submit issues and feature requests for documentation, since documentation does not have a single "corresponding GitHub repository". +- The governance policies call out the Contributors and Maintainers project + roles, and mention that doc changes require one maintainer approval. They + should also define Doc Contributors as a role, with information on + documentation standards, and who should review such changes. +- The CONTRIBUTING page should explicitly mention documentation changes as + distinct from "making code changes" as an area of contribution. +- The CONTRIBUTING page needs explicit information for how to submit issues and + feature requests for documentation, since documentation does not have a single + "corresponding GitHub repository". ## Website analysis | Criteria | 1 | 2 | 3 | 4 | 5 | -| --- | --- | --- | --- | --- | --- | -| Single-source for all files | | | | x | | -| Meets min website req. (for maturity level) | | x | | | | -| Branding and design | | | | x | | -| Case studies/social proof | | | x | | | -| Maintenance planning | | | x | | | -| A11y plan & implementation | | | x | | | -| Mobile-first plan & impl. | | | | | x | +| ------------------------------------------- | --- | --- | --- | --- | --- | +| Single-source for all files | | | | x | | +| Meets min website req. (for maturity level) | | x | | | | +| Branding and design | | | | x | | +| Case studies/social proof | | | x | | | +| Maintenance planning | | | x | | | +| A11y plan & implementation | | | x | | | +| Mobile-first plan & impl. | | | | | x | | HTTPS access & HTTP redirect | | | | | x | -| Google Analytics 4 for production only | x | | | | | -| Indexing allowed for production server only | | | | | x | -| Intra-site / local search | | x | | | | -| Account custodians are documented | x | | | | | +| Google Analytics 4 for production only | x | | | | | +| Indexing allowed for production server only | | | | | x | +| Intra-site / local search | | x | | | | +| Account custodians are documented | x | | | | | Scale: @@ -211,41 +308,57 @@ Scale: **Single-source for all files**: Source is in in-toto.io repo. -**Meets min website req. (for Incubating)**: Doc assessment is in progress. Very little documentation is published directly on the website. Most docs are in GitHub, only a few of those are directly linked from the website. +**Meets min website req. (for Incubating)**: Doc assessment is in progress. Very +little documentation is published directly on the website. Most docs are in +GitHub, only a few of those are directly linked from the website. -**Branding and design**: Brand is evident across the website but the button component is an exception; it does not conform to the in-toto design/brand. +**Branding and design**: Brand is evident across the website but the button +component is an exception; it does not conform to the in-toto design/brand. -**Case studies/social proof**: Menu item About > Adoptions & Integrations links to a GitHub repo with folders created and maintained by adopters. No icons or listing of adopters appear on the web site. +**Case studies/social proof**: Menu item About > Adoptions & Integrations links +to a GitHub repo with folders created and maintained by adopters. No icons or +listing of adopters appear on the web site. -**Maintenance planning**: The Website runs on Hugo, which is well supported by the community. It’s hard to tell who maintains what. In other words, there are no custodians for website maintenance. +**Maintenance planning**: The Website runs on Hugo, which is well supported by +the community. It’s hard to tell who maintains what. In other words, there are +no custodians for website maintenance. -**A11y plan & implementation**: The in-toto website is accessible but lacks in some vital areas such as element naming, color contrast, and internationalization. +**A11y plan & implementation**: The in-toto website is accessible but lacks in +some vital areas such as element naming, color contrast, and +internationalization. -**HTTPS access & HTTP redirect**: HTTPS is the default, HTTP redirects correctly. +**HTTPS access & HTTP redirect**: HTTPS is the default, HTTP redirects +correctly. -**Intra-site / local search**: There is no site map or search mechanism; the only navigation is through a minimal menu bar. +**Intra-site / local search**: There is no site map or search mechanism; the +only navigation is through a minimal menu bar. ### Recommendations **Meets min website req. (for Incubating)**, **Intra-site / local search** -Reassess these areas after adopting recommendation to transfer most of the documentation to the website. +Reassess these areas after adopting recommendation to transfer most of the +documentation to the website. **A11y plan & implementation** The following changes will improve accessibility for all users: + - Images: Image elements must have an alt attribute. -- Color contrast: Button background and foreground colors do not have enough contrast. -Primary recommendation is to use a darker color as background and lighter color as foreground. -The background color should match with the project's brand color. +- Color contrast: Button background and foreground colors do not have enough + contrast. Primary recommendation is to use a darker color as background and + lighter color as foreground. The background color should match with the + project's brand color. - Internationalization: The HTML tag must have a lang attribute set. **Analytics for production-only website** -Add analytics added to help monitor site traffic and diagnose issues like 404. -CNCF recommends you use the Google Analytics 4 (GA4) tool; note that the project must be added to the CNCF's GA4 account. -Feel free to reach out to the CNCF team via the Service Desk platform for further assistance. +Add analytics added to help monitor site traffic and diagnose issues like 404. +CNCF recommends you use the Google Analytics 4 (GA4) tool; note that the project +must be added to the CNCF's GA4 account. Feel free to reach out to the CNCF team +via the Service Desk platform for further assistance. **Maintenance planning** -Document account custodians by setting up an OWNERS.md file listing each maintainer and their respective area of ownership. +Document account custodians by setting up an OWNERS.md file listing each +maintainer and their respective area of ownership. diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md index 78442d7..b747401 100644 --- a/analyses/0009-in-toto/in-toto-doc-issues.md +++ b/analyses/0009-in-toto/in-toto-doc-issues.md @@ -1,84 +1,148 @@ -# Documentation Issues +# Documentation Issues + +These issues identify and classify tasks that contributors can undertake to +establish a set of organized and navigable documents on the in-toto public +website. + +## Create **Doc home page** + +The landing page for the +[read-the-docs site](https://in-toto.readthedocs.io/en/latest/), which currently +lands on the auto-generated Python reference doc, could be expanded and +repurposed as the new overall **Doc home page**. + +- [ ] To be immediately useful, the landing page should provide a _top-level + roadmap_ to existing docs. See + [Survey of existing doc](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md) + + This is a necessary step in raising the maturity level of this project. The + roadmap should initially describe and provide access to: + + - Specification + - Basic demo + - Python reference implementation along with its reference docs (which need to + move into a sub-directory) + - Overview of the git repo structure. + +- [ ] Move the Description and pointer to the Python Reference implementation to + an Implementations section, and move the RTD reference docs for it into + this section. + +- [ ] Create a doc contributors policy requiring that the Doc home page be + updated to reflect any changes to the doc locations and structure. + +## Expose new-user information + +- [ ] Move the content of the + [README for the main repo](https://github.com/in-toto/in-toto) to a + separate **"Getting Started" document**. + + - [ ] Add a prominent pointer to the new **"Getting Started" document** on the + in-toto home page, such as the top menu item in the "Get Started" menu. + - [ ] Replace the README with brief introductory notes that link to the + documentation. + +- [ ] As a stop-gap, add a top-level TOC for the existing Specification to show + what is in it. + +- [ ] Move important sections out of the spec into separate documents, and add + them to the Doc home-page TOC. + - [ ] Evaluate the depth of the + [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) + and decide which user population it is most suitable for, or adapt it to + new tailored versions. + - [ ] Expose + [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology) + as a separate document, formatted in an alphabetized table for easy + reference. + - [ ] Expose + [Workflow Description](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md#51-workflow-description), + which identifies the different user roles, as a separate document. + - [ ] Adapt the content to point to appropriate doc for each role that would + be particularly helpful to new users. -These issues identify and classify tasks that contributors can undertake to establish a set of organized and navigable documents on the in-toto public website. - -## Create **Doc home page** - - The landing page for the [read-the-docs site](https://in-toto.readthedocs.io/en/latest/), which currently lands on the auto-generated Python reference doc, could be expanded and repurposed as the new overall **Doc home page**. - - - [ ] To be immediately useful, the landing page should provide a *top-level roadmap* to existing docs. See [Survey of existing doc](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md) - - This is a necessary step in raising the maturity level of this project. The roadmap should initially describe and provide access to: - - Specification - - Basic demo - - Python reference implementation along with its reference docs (which need to move into a sub-directory) - - Overview of the git repo structure. - - - [ ] Move the Description and pointer to the Python Reference implementation to an Implementations section, and move the RTD reference docs for it into this section. - - - [ ] Create a doc contributors policy requiring that the Doc home page be updated to reflect any changes to the doc locations and structure. - -## Expose new-user information - - - [ ] Move the content of the [README for the main repo](https://github.com/in-toto/in-toto) to a separate **"Getting Started" document**. - - [ ] Add a prominent pointer to the new **"Getting Started" document** on the in-toto home page, such as the top menu item in the "Get Started" menu. - - [ ] Replace the README with brief introductory notes that link to the documentation. - - - [ ] As a stop-gap, add a top-level TOC for the existing Specification to show what is in it. +## Create **High-level technical overviews** of increasing depth - - [ ] Move important sections out of the spec into separate documents, and add them to the Doc home-page TOC. - - [ ] Evaluate the depth of the [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) and decide which user population it is most suitable for, or adapt it to new tailored versions. - - [ ] Expose [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology) as a separate document, formatted in an alphabetized table for easy reference. - - [ ] Expose [Workflow Description](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md#51-workflow-description), which identifies the different user roles, as a separate document. - - [ ] Adapt the content to point to appropriate doc for each role that would be particularly helpful to new users. +Arrange and choose content from existing overviews to create a set of overviews +addressed to specific audiences: evaluators and new users/adopters, experienced +users and administrators, contributors of different types (ITE proposers, doc +writers and editors...). -## Create **High-level technical overviews** of increasing depth - - Arrange and choose content from existing overviews to create a set of overviews addressed to specific audiences: - evaluators and new users/adopters, experienced users and administrators, contributors of different types (ITE proposers, doc writers and editors...). - - A basic intro, possibly suitable for evaluators, is already linked directly from the [home page About tab](https://in-toto.io/in-toto/). - The short intro links to the [latest spec in GitHub](https://github.com/in-toto/docs/blob/master/in-toto-spec.md), which contains a more comprehensive overview. - (NOTE: The [PDF link to the stable spec](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf) is broken. This should be fixed or removed.) +A basic intro, possibly suitable for evaluators, is already linked directly from +the [home page About tab](https://in-toto.io/in-toto/). The short intro links to +the +[latest spec in GitHub](https://github.com/in-toto/docs/blob/master/in-toto-spec.md), +which contains a more comprehensive overview. (NOTE: The +[PDF link to the stable spec](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf) +is broken. This should be fixed or removed.) - - [ ] Initially, transfer the tech overview content from the Specification into a top-level Technical Overview document in RTD, and link as "Read more..." from the basic one. +- [ ] Initially, transfer the tech overview content from the Specification into + a top-level Technical Overview document in RTD, and link as "Read more..." + from the basic one. - - [ ] Determine whether the Tech Overview currently in the spec is suitable for new users or for contributors, and adapt or create another version of suitable depth for the other audience. +- [ ] Determine whether the Tech Overview currently in the spec is suitable for + new users or for contributors, and adapt or create another version of + suitable depth for the other audience. - - [ ] The most in-depth overview should also point to academic papers for further architectural detail: - https://www.usenix.org/system/files/sec19-torres-arias.pdf, https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias +- [ ] The most in-depth overview should also point to academic papers for + further architectural detail: + https://www.usenix.org/system/files/sec19-torres-arias.pdf, + https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias ## Sort the layered technical overviews by increasing depth, and use that as a guide to create the overall doc architecture. - - [ ] Add overviews as text-only pages to RTD. +- [ ] Add overviews as text-only pages to RTD. - - [ ] Make each tech overview the introductory page to a section aimed primarily at the appropriate user role or roles. - - - [ ] In each section, include an index to current doc (mostly in GitHub Readme files) relevant to the audience. For example, the [ITE spec](https://github.com/in-toto/ITE/blob/master/ITE/1/README.adoc) that describes the ITE process, which is two levels down from main in the [ITE repo](https://github.com/in-toto/ITE/). The document should be referenced in the section for Contributors, and possibly a subsection sepecifically intended for ITE proposers and developers. +- [ ] Make each tech overview the introductory page to a section aimed primarily + at the appropriate user role or roles. - - [ ] As documents are transfered from GitHub into the Doc web site, update the index accordingly and adjust the doc architecture as needed. +- [ ] In each section, include an index to current doc (mostly in GitHub Readme + files) relevant to the audience. For example, the + [ITE spec](https://github.com/in-toto/ITE/blob/master/ITE/1/README.adoc) + that describes the ITE process, which is two levels down from main in the + [ITE repo](https://github.com/in-toto/ITE/). The document should be + referenced in the section for Contributors, and possibly a subsection + sepecifically intended for ITE proposers and developers. -## Establish policy for reference material +- [ ] As documents are transfered from GitHub into the Doc web site, update the + index accordingly and adjust the doc architecture as needed. - The doc roadmap should clearly identify and link to the existing generated pages as *reference* doc for the Python reference implementation. - It should also list and link to reference docs for other implementations. +## Establish policy for reference material - - [ ] Decide where reference docs for different implementations should live in the doc structure and where their sources live in the repo structure. +The doc roadmap should clearly identify and link to the existing generated pages +as _reference_ doc for the Python reference implementation. It should also list +and link to reference docs for other implementations. - - [ ] Publish the policy and procedures for developers to document their implementations. - - - [ ] Develop a documentation policy for implementers. - For example, the auto-generated doc for the [Go implementation](https://pkg.go.dev/github.com/in-toto/in-toto-golang) is not at all parallel with the Python RTD reference doc - it is all in GitHub, and has no introductory or explanatory content, or navigational aids. +- [ ] Decide where reference docs for different implementations should live in + the doc structure and where their sources live in the repo structure. -## Define content creation process +- [ ] Publish the policy and procedures for developers to document their + implementations. - - [ ] The [read-the-docs site](https://in-toto.readthedocs.io/en/latest/) has an [Edit the Doc button](https://github.com/in-toto/in-toto/blob/develop/doc/source/index.rst). Instead of pointing directly to the source files, make the button point to a page with instructions for [doc contributors](https://github.com/in-toto/community/blob/main/CONTRIBUTING.md), and a link to the [governance policies](https://github.com/in-toto/community/blob/main/GOVERNANCE.md). +- [ ] Develop a documentation policy for implementers. For example, the + auto-generated doc for the + [Go implementation](https://pkg.go.dev/github.com/in-toto/in-toto-golang) + is not at all parallel with the Python RTD reference doc - it is all in + GitHub, and has no introductory or explanatory content, or navigational + aids. - - [ ] Decide on a structure for documentation directories and source files in the project doc repo. +## Define content creation process - - [ ] Make sure the policy pages include or link to: - - Contact info for maintainer/reviewer for documentation contributions. - - Available doc style guides/templates (as well as code standards) - - Usage guidelines for RTD (or other doc tool) and any project-specific usage standards. - - Current doc architecture plan. - - Map to documentation source files. +- [ ] The [read-the-docs site](https://in-toto.readthedocs.io/en/latest/) has an + [Edit the Doc button](https://github.com/in-toto/in-toto/blob/develop/doc/source/index.rst). + Instead of pointing directly to the source files, make the button point to + a page with instructions for + [doc contributors](https://github.com/in-toto/community/blob/main/CONTRIBUTING.md), + and a link to the + [governance policies](https://github.com/in-toto/community/blob/main/GOVERNANCE.md). + +- [ ] Decide on a structure for documentation directories and source files in + the project doc repo. + +- [ ] Make sure the policy pages include or link to: + - Contact info for maintainer/reviewer for documentation contributions. + - Available doc style guides/templates (as well as code standards) + - Usage guidelines for RTD (or other doc tool) and any project-specific usage + standards. + - Current doc architecture plan. + - Map to documentation source files. diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md index 574ddc3..85bd9de 100644 --- a/analyses/0009-in-toto/in-toto-implementation.md +++ b/analyses/0009-in-toto/in-toto-implementation.md @@ -1,142 +1,257 @@ # Implementation ## Organizational principles -Review the [CNCF website design guidelines](https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md) for project home page and architecture recommendations. Consult with CNCF TechDocs or other technical documentation specialists to develop an appropriate information architecture based on different user roles and their specific tasks and information needs. -To efficiently transfer relevant information to the people who need it, organize documentation with the product users' roles in mind. For example: - -- End-users with specific roles should be clearly directed to instructional material for performing specific tasks. -- Administrators who are configuring the tool have a different set of tasks, and require different instructions and reference material. -- Spec implementors are another reader population who need information on how to provide reference doc for their implementations. -- Contributors should be pointed to the contribution and governance rules, and be able to find good first issues to get started on. - -Similarly, the depth and detail of introductory conceptual material should be clearly addressed to and tailored to: - -- *Evaluators* who are deciding whether to adopt the tools and methodology. This could be on the main website, with a marketing slant. -- *New users* who will need to either integrate or configure the tools. This could be the intro that is on or linked prominently from the Doc Home Page. -- *Potential contributors* who are planning to extend the tools or implement the specification. These readers require more depth of information about the architectural intentions and decision criteria, which would just be confusing and unnecessary to other reader populations. - -See a more detailed analysis of reader roles and their documentation needs below. +Review the +[CNCF website design guidelines](https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md) +for project home page and architecture recommendations. Consult with CNCF +TechDocs or other technical documentation specialists to develop an appropriate +information architecture based on different user roles and their specific tasks +and information needs. + +To efficiently transfer relevant information to the people who need it, organize +documentation with the product users' roles in mind. For example: + +- End-users with specific roles should be clearly directed to instructional + material for performing specific tasks. +- Administrators who are configuring the tool have a different set of tasks, and + require different instructions and reference material. +- Spec implementors are another reader population who need information on how to + provide reference doc for their implementations. +- Contributors should be pointed to the contribution and governance rules, and + be able to find good first issues to get started on. + +Similarly, the depth and detail of introductory conceptual material should be +clearly addressed to and tailored to: + +- _Evaluators_ who are deciding whether to adopt the tools and methodology. This + could be on the main website, with a marketing slant. +- _New users_ who will need to either integrate or configure the tools. This + could be the intro that is on or linked prominently from the Doc Home Page. +- _Potential contributors_ who are planning to extend the tools or implement the + specification. These readers require more depth of information about the + architectural intentions and decision criteria, which would just be confusing + and unnecessary to other reader populations. + +See a more detailed analysis of reader roles and their documentation needs +below. ### User roles -To get the right information to the right reader, each page should be explicitly addressed to a specific audience, and the organization and navigation for the site should explicitly direct users of different types to relevant sections. - -- The website (both the in-toto home page and the doc home page) should clearly identify and name the user roles, and what users in those roles need and can reasonably expect from in-toto documentation. -- The documentation should be organized into sections that are clearly aimed at users in specific roles with similar goals and information needs. -- If a page is useful for users with different roles, it should be linked from the section overviews for all relevant roles. - -Users with the following roles are potential audiences for in-toto project documentation. - -| User Role | Doc needs | -| --- | --- | -| **Evaluators** determine whether in-toto meets their needs and can be implemented in their organization. | High-level technical overview with a marketing slant, analysis of business benefits, adoption and success stories, and a workflow overview. | -| **End users** can be *Project owners* and *Functionaries*. | End users can be new or experienced. New users need a clear learning path and general examples. Experienced users need reference docs and use-case examples. | -| **Project owners** define the layout to be followed when, e.g., using the in-toto CLI tools. When doing so, they specify who is intended to sign for every piece of link metadata, any sublayouts that may exist, and how to further verify accompanying metadata. | New users need an overview, demos, templates, and basic instructions. Experienced users need deeper architectural info, use cases, and examples. | -| **Functionaries** perform the intended actions and produce link metadata for each step. | *?? do these users read in-toto doc at all, or is the project owner responsible for instructing them in how to sign and verify their steps??* | -| **Contributors** can be contributors to the *code* base and to the *documentation* of the OSS project itself. | Contributors need project standards and instructions, community guidelines, and GitHub instructions specific to the project. This information is often in the repo, and not in the project or product documentation. | -| **Code contributors** are members of the community who: *make code changes*, *submit changes to specifications*, *create new integrations*, and *submit issues, feature requests and more* | These contributors need to understand the GitHub repo structure, the contribution policies and procedures, coding and naming standards and conventions. ITE developers and integrators need direction on how and where to document their own additions. | -| **Doc contributors** (to be added) are members of the community who use the **Edit** button to make changes to published documents, or create new documentation. | These contributors need clear doc contribution standards, naming and style conventions, and clear instructions on how to create or edit existing doc, and where documents should go (that is, what should go on the website or in GitHub, where a subject fits in the doc architecture) | - +To get the right information to the right reader, each page should be explicitly +addressed to a specific audience, and the organization and navigation for the +site should explicitly direct users of different types to relevant sections. + +- The website (both the in-toto home page and the doc home page) should clearly + identify and name the user roles, and what users in those roles need and can + reasonably expect from in-toto documentation. +- The documentation should be organized into sections that are clearly aimed at + users in specific roles with similar goals and information needs. +- If a page is useful for users with different roles, it should be linked from + the section overviews for all relevant roles. + +Users with the following roles are potential audiences for in-toto project +documentation. + +| User Role | Doc needs | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Evaluators** determine whether in-toto meets their needs and can be implemented in their organization. | High-level technical overview with a marketing slant, analysis of business benefits, adoption and success stories, and a workflow overview. | +| **End users** can be _Project owners_ and _Functionaries_. | End users can be new or experienced. New users need a clear learning path and general examples. Experienced users need reference docs and use-case examples. | +| **Project owners** define the layout to be followed when, e.g., using the in-toto CLI tools. When doing so, they specify who is intended to sign for every piece of link metadata, any sublayouts that may exist, and how to further verify accompanying metadata. | New users need an overview, demos, templates, and basic instructions. Experienced users need deeper architectural info, use cases, and examples. | +| **Functionaries** perform the intended actions and produce link metadata for each step. | _?? do these users read in-toto doc at all, or is the project owner responsible for instructing them in how to sign and verify their steps??_ | +| **Contributors** can be contributors to the _code_ base and to the _documentation_ of the OSS project itself. | Contributors need project standards and instructions, community guidelines, and GitHub instructions specific to the project. This information is often in the repo, and not in the project or product documentation. | +| **Code contributors** are members of the community who: _make code changes_, _submit changes to specifications_, _create new integrations_, and _submit issues, feature requests and more_ | These contributors need to understand the GitHub repo structure, the contribution policies and procedures, coding and naming standards and conventions. ITE developers and integrators need direction on how and where to document their own additions. | +| **Doc contributors** (to be added) are members of the community who use the **Edit** button to make changes to published documents, or create new documentation. | These contributors need clear doc contribution standards, naming and style conventions, and clear instructions on how to create or edit existing doc, and where documents should go (that is, what should go on the website or in GitHub, where a subject fits in the doc architecture) | ## General doc plan -To begin achieving the goal of documentation that meets the needs of different user populations and is discoverable by the intended readers, we recommend the following general plan. + +To begin achieving the goal of documentation that meets the needs of different +user populations and is discoverable by the intended readers, we recommend the +following general plan. 1. Initial tasks: - a. Create a Documentation home page on the [project web site](https://in-toto.io), linked prominently from the About menu. + a. Create a Documentation home page on the + [project web site](https://in-toto.io), linked prominently from the About + menu. + + b. Create a **Getting Started** page on the web site from the existing README + content in the [main repo](https://github.com/in-toto/in-toto.README.md). - b. Create a **Getting Started** page on the web site from the existing README content in the [main repo](https://github.com/in-toto/in-toto.README.md). + c. Link **Getting Started** as the first menu item in the **Get started** + menu (currently the first item is a link to a demo). - c. Link **Getting Started** as the first menu item in the **Get started** menu (currently the first item is a link to a demo). + d. Expose parts of the product specification as separate named documents on + the website, as: - d. Expose parts of the product specification as separate named documents on the website, as: - - [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) (compare content to https://in-toto.io/in-toto/README and current website About - create versions of increasing depth to address to specific audiences) - - [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology) (convert to alphabetized table) - - [Workflow/Personas](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) (clearly identify user types and point to relevant doc sections) + - [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) + (compare content to https://in-toto.io/in-toto/README and current website + About - create versions of increasing depth to address to specific + audiences) + - [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology) + (convert to alphabetized table) + - [Workflow/Personas](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) + (clearly identify user types and point to relevant doc sections) -2. Create a high-level technical overview on the project home page suitable for evaluators (see [User Roles](#user-roles)). This might be one of the existing overviews, or can be adapted from them. +2. Create a high-level technical overview on the project home page suitable for + evaluators (see [User Roles](#user-roles)). This might be one of the existing + overviews, or can be adapted from them. -3. Create an index or map to existing docs as a temporary guide, preparatory to moving that information into RTD and integrating it into a doc architecture. +3. Create an index or map to existing docs as a temporary guide, preparatory to + moving that information into RTD and integrating it into a doc architecture. 4. Encourage documentation contributions: - - Add Documentation as a contribution area, and clarify the process. Contributor docs should: - - List reviewers/approvers for doc changes and additions. - - Encourage the use of Documentation and Good First Issue tags for issues and PRs. - - Make doc contributors responsible for updating doc roadmaps/ToCs, to reflect any changes they make to the doc structure (adding or moving documents). - - Specify a documentation "champion" to review and approve doc PRs, decide doc issue priorities -- Justin Cappos? + - Add Documentation as a contribution area, and clarify the process. + Contributor docs should: + - List reviewers/approvers for doc changes and additions. + - Encourage the use of Documentation and Good First Issue tags for issues + and PRs. + - Make doc contributors responsible for updating doc roadmaps/ToCs, to + reflect any changes they make to the doc structure (adding or moving + documents). + - Specify a documentation "champion" to review and approve doc PRs, decide + doc issue priorities -- Justin Cappos? - Develop doc standards (style guide, page templates, locations) - Develop doc architecture - - Develop and document a doc versioning/update process that includes updating the Doc home page as locations change and doc is added. + - Develop and document a doc versioning/update process that includes updating + the Doc home page as locations change and doc is added. ## Actionable items -1. Create **Doc home page** - - The landing page for the [read-the-docs site](https://in-toto.readthedocs.io/en/latest/), which currently lands on the auto-generated Python reference doc, could be expanded and repurposed as the new overall **Doc home page**. - - This is a necessary step in raising the maturity level of this project. Initially, the page should be a roadmap that describes and provides access to: - - Specification - - Basic demo - - Python reference implementation along with its reference docs (which need to move into a sub-directory) - - Overview of the git repo structure. - - 1.1 Create a *top-level roadmap* to [existing docs](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md) at the location decided on for the Doc home page. - - 1.2 Move the Description and pointer to the Python Reference implementation to an **Implementations** section, and move the RTD reference docs for it into this section. - - 1.3 Create a doc contributors policy requiring that the Doc home page be updated to reflect any changes to the doc locations and structure. - -2. Expose new-user information - - 2.1 Move the content of the [README for the main repo](https://github.com/in-toto/in-toto) to a separate **"Getting Started" document**, with a prominent pointer on the in-toto home page, such as the top menu item in the "Get Started" menu. Replace the README with brief introductory notes that link to the documentation. - - 2.2 As a stop-gap, add a top-level TOC for the existing Specification to show what is in it. - - 2.3 Move important sections out of the spec into separate documents, and add them to the Doc home-page TOC. - - Evaluate the depth of the [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) and decide which user population it is most suitable for, or adapt it to new tailored versions. - - Expose [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology) as a separate document, formatted in an alphabetized table for easy reference. - - Expose [Workflow Description](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md#51-workflow-description), which identifies the different user roles. Adapt this to a separate document that also points to the appropriate doc for each role, which would be particularly helpful to new users. - -3. Arrange and choose content from existing overviews to create **High-level technical overviews** of increasing depth, addressed to specific audiences (evaluators, new users/adopters, experienced users and administrators, contributors of different types (ITE proposers, doc writers and editors...). - - A basic intro, possibly suitable for evaluators, is already linked directly from the [home page About tab](https://in-toto.io/in-toto/). The short intro links to the [latest spec in GitHub](https://github.com/in-toto/docs/blob/master/in-toto-spec.md), which contains a more comprehensive overview. (NOTE: The [PDF link to the stable spec](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf) is broken. This should be fixed or removed.) - - 3.1 Initially, transfer the tech overview content from the Specification into a top-level Technical Overview document in RTD, and link as "Read more..." from the basic one. - - 3.2 Determine whether the Tech Overview currently in the spec is suitable for new users or for contributors, and adapt or create another version of suitable depth for the other audience. - - 3.3 The most in-depth overview should also point to academic papers for further architectural detail: - https://www.usenix.org/system/files/sec19-torres-arias.pdf, https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias - -4. Sort the layered technical overviews by increasing depth, and use that as a guide to create the overall doc architecture. +1. Create **Doc home page** + + The landing page for the + [read-the-docs site](https://in-toto.readthedocs.io/en/latest/), which + currently lands on the auto-generated Python reference doc, could be expanded + and repurposed as the new overall **Doc home page**. + + This is a necessary step in raising the maturity level of this project. + Initially, the page should be a roadmap that describes and provides access + to: - Specification - Basic demo - Python reference implementation along with + its reference docs (which need to move into a sub-directory) - Overview of + the git repo structure. + + 1.1 Create a _top-level roadmap_ to + [existing docs](https://github.com/jbogarthyde/CNCF-techdocs/main/assessments/0009-in-toto/survey-of-existing-doc.md) + at the location decided on for the Doc home page. + + 1.2 Move the Description and pointer to the Python Reference implementation + to an **Implementations** section, and move the RTD reference docs for it + into this section. + + 1.3 Create a doc contributors policy requiring that the Doc home page be + updated to reflect any changes to the doc locations and structure. + +2. Expose new-user information + + 2.1 Move the content of the + [README for the main repo](https://github.com/in-toto/in-toto) to a separate + **"Getting Started" document**, with a prominent pointer on the in-toto home + page, such as the top menu item in the "Get Started" menu. Replace the README + with brief introductory notes that link to the documentation. + + 2.2 As a stop-gap, add a top-level TOC for the existing Specification to show + what is in it. + + 2.3 Move important sections out of the spec into separate documents, and add + them to the Doc home-page TOC. + + - Evaluate the depth of the + [System Overview](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#2-system-overview) + and decide which user population it is most suitable for, or adapt it to + new tailored versions. + - Expose + [Glossary](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#17-terminology) + as a separate document, formatted in an alphabetized table for easy + reference. + - Expose + [Workflow Description](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md#51-workflow-description), + which identifies the different user roles. Adapt this to a separate + document that also points to the appropriate doc for each role, which would + be particularly helpful to new users. + +3. Arrange and choose content from existing overviews to create **High-level + technical overviews** of increasing depth, addressed to specific audiences + (evaluators, new users/adopters, experienced users and administrators, + contributors of different types (ITE proposers, doc writers and editors...). + + A basic intro, possibly suitable for evaluators, is already linked directly + from the [home page About tab](https://in-toto.io/in-toto/). The short intro + links to the + [latest spec in GitHub](https://github.com/in-toto/docs/blob/master/in-toto-spec.md), + which contains a more comprehensive overview. (NOTE: The + [PDF link to the stable spec](https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.pdf) + is broken. This should be fixed or removed.) + + 3.1 Initially, transfer the tech overview content from the Specification into + a top-level Technical Overview document in RTD, and link as "Read more..." + from the basic one. + + 3.2 Determine whether the Tech Overview currently in the spec is suitable for + new users or for contributors, and adapt or create another version of + suitable depth for the other audience. + + 3.3 The most in-depth overview should also point to academic papers for + further architectural detail: + https://www.usenix.org/system/files/sec19-torres-arias.pdf, + https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias + +4. Sort the layered technical overviews by increasing depth, and use that as a + guide to create the overall doc architecture. 4.1 Add overviews as text-only pages to RTD. - 4.2 Make each tech overview the introductory page to a section aimed primarily at the appropriate user role or roles. - - 4.3 In each section, include an index to current doc (mostly in GitHub Readme files) relevant to the audience. For example, the [ITE spec](https://github.com/in-toto/ITE/blob/master/ITE/1/README.adoc) that describes the ITE process, which is two levels down from main in the [ITE repo](https://github.com/in-toto/ITE/). The document should be referenced in the section for Contributors, and possibly a subsection sepecifically intended for ITE proposers and developers. + 4.2 Make each tech overview the introductory page to a section aimed + primarily at the appropriate user role or roles. - 4.4 As documents are transfered from GitHub into the Doc web site, update the index accordingly and adjust the doc architecture as needed. + 4.3 In each section, include an index to current doc (mostly in GitHub Readme + files) relevant to the audience. For example, the + [ITE spec](https://github.com/in-toto/ITE/blob/master/ITE/1/README.adoc) that + describes the ITE process, which is two levels down from main in the + [ITE repo](https://github.com/in-toto/ITE/). The document should be + referenced in the section for Contributors, and possibly a subsection + sepecifically intended for ITE proposers and developers. + + 4.4 As documents are transfered from GitHub into the Doc web site, update the + index accordingly and adjust the doc architecture as needed. 5. Reference material - 5.1 Decide where reference docs for different implementations should live in the doc structure and where their sources live in the repo structure. - The doc roadmap should clearly identify and link to the existing generated pages as *reference* doc for the Python reference implementation. It should also list and link to reference docs for other implementations. + 5.1 Decide where reference docs for different implementations should live in + the doc structure and where their sources live in the repo structure. The doc + roadmap should clearly identify and link to the existing generated pages as + _reference_ doc for the Python reference implementation. It should also list + and link to reference docs for other implementations. + + 5.2 Publish the policy and procedures for developers to document their + implementations. - 5.2 Publish the policy and procedures for developers to document their implementations. - - Develop a documentation policy for implementers. - For example, the auto-generated doc for the [Go implementation](https://pkg.go.dev/github.com/in-toto/in-toto-golang) is not at all parallel with the Python RTD reference doc - it is all in GitHub, and has no introductory or explanatory content, or navigational aids. + - Develop a documentation policy for implementers. For example, the + auto-generated doc for the + [Go implementation](https://pkg.go.dev/github.com/in-toto/in-toto-golang) + is not at all parallel with the Python RTD reference doc - it is all in + GitHub, and has no introductory or explanatory content, or navigational + aids. 6. Content creation process - 6.1 The [read-the-docs site](https://in-toto.readthedocs.io/en/latest/) has an [Edit the Doc button](https://github.com/in-toto/in-toto/blob/develop/doc/source/index.rst). Instead of pointing directly to the source files, make the button point to a page with instructions for [doc contributors](https://github.com/in-toto/community/blob/main/CONTRIBUTING.md), and a link to the [governance policies](https://github.com/in-toto/community/blob/main/GOVERNANCE.md). + 6.1 The [read-the-docs site](https://in-toto.readthedocs.io/en/latest/) has + an + [Edit the Doc button](https://github.com/in-toto/in-toto/blob/develop/doc/source/index.rst). + Instead of pointing directly to the source files, make the button point to a + page with instructions for + [doc contributors](https://github.com/in-toto/community/blob/main/CONTRIBUTING.md), + and a link to the + [governance policies](https://github.com/in-toto/community/blob/main/GOVERNANCE.md). - 6.2 Decide on a structure for documentation directories and source files in the project doc repo. + 6.2 Decide on a structure for documentation directories and source files in + the project doc repo. 6.3 Make sure the policy pages include or link to: - - Contact info for maintainer/reviewer for documentation contributions. - - Available doc style guides/templates (as well as code standards) - - Usage guidelines for RTD (or other doc tool) and any project-specific usage standards. - - Current doc architecture plan. - - Map to documentation source files. + + - Contact info for maintainer/reviewer for documentation contributions. + - Available doc style guides/templates (as well as code standards) + - Usage guidelines for RTD (or other doc tool) and any project-specific usage + standards. + - Current doc architecture plan. + - Map to documentation source files. diff --git a/analyses/0009-in-toto/survey-of-existing-doc.md b/analyses/0009-in-toto/survey-of-existing-doc.md index acdeb97..55fb1fe 100644 --- a/analyses/0009-in-toto/survey-of-existing-doc.md +++ b/analyses/0009-in-toto/survey-of-existing-doc.md @@ -1,67 +1,69 @@ # Survey of existing documentation as of 09/2023 The following links are loosely sorted into conceptual categories. - + **Doc issue from contributor**: https://github.com/in-toto/community/issues/9 **Home page** https://in-toto.io/ -**GitHub repo for home page**: https://github.com/in-toto/in-toto.io +**GitHub repo for home page**: https://github.com/in-toto/in-toto.io **Specifications** - https://github.com/in-toto/docs/blob/master/in-toto-spec.md -(also contains most of the user doc) + https://github.com/in-toto/docs/blob/master/in-toto-spec.md (also contains most +of the user doc) - https://github.com/in-toto/attestation +https://github.com/in-toto/attestation -+ language-specific implementations of spec +- language-specific implementations of spec - https://github.com/in-toto/in-toto-java + https://github.com/in-toto/in-toto-java - https://github.com/in-toto/in-toto-rs + https://github.com/in-toto/in-toto-rs - https://github.com/in-toto/in-toto-golang + https://github.com/in-toto/in-toto-golang -+ GitHub repo READMEs +- GitHub repo READMEs - https://github.com/in-toto/in-toto + https://github.com/in-toto/in-toto - https://github.com/in-toto/demo + https://github.com/in-toto/demo -+ Doc generation repo: https://github.com/in-toto/docs +- Doc generation repo: https://github.com/in-toto/docs - + Generated (read-the-docs) for Python reference implementation + - Generated (read-the-docs) for Python reference implementation - + Installation https://in-toto.readthedocs.io/en/latest/installing.html + - Installation https://in-toto.readthedocs.io/en/latest/installing.html - + CLI https://in-toto.readthedocs.io/en/latest/command-line-tools/index.html + - CLI https://in-toto.readthedocs.io/en/latest/command-line-tools/index.html - + API https://in-toto.readthedocs.io/en/latest/api.html + - API https://in-toto.readthedocs.io/en/latest/api.html - + Metadata model https://in-toto.readthedocs.io/en/latest/model.html + - Metadata model https://in-toto.readthedocs.io/en/latest/model.html - + Configuration https://in-toto.readthedocs.io/en/latest/configuration.html + - Configuration https://in-toto.readthedocs.io/en/latest/configuration.html - + Layout example https://in-toto.readthedocs.io/en/latest/layout-creation-example.html (+ ptr to demo, not in read-the-docs) + - Layout example + https://in-toto.readthedocs.io/en/latest/layout-creation-example.html (+ ptr + to demo, not in read-the-docs) -+ ITE = in-toto Enhancements (additions to specification) +- ITE = in-toto Enhancements (additions to specification) - https://github.com/in-toto/ITE/blob/master/README.md + https://github.com/in-toto/ITE/blob/master/README.md - https://github.com/in-toto/ITE/blob/master/ITE/1/README.adoc#abstract + https://github.com/in-toto/ITE/blob/master/ITE/1/README.adoc#abstract -+ Contributor and Community +- Contributor and Community - https://github.com/in-toto/community/blob/main/README.md + https://github.com/in-toto/community/blob/main/README.md - https://github.com/in-toto/community/blob/main/CONTRIBUTING.md + https://github.com/in-toto/community/blob/main/CONTRIBUTING.md - https://github.com/in-toto/community/blob/main/CODE-OF-CONDUCT.md + https://github.com/in-toto/community/blob/main/CODE-OF-CONDUCT.md - https://github.com/in-toto/friends (ongoing & complete integrations) + https://github.com/in-toto/friends (ongoing & complete integrations) -+ Academic papers (PDFs) +- Academic papers (PDFs) - https://www.usenix.org/system/files/sec19-torres-arias.pdf + https://www.usenix.org/system/files/sec19-torres-arias.pdf - https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias + https://www.usenix.org/conference/usenixsecurity19/presentation/torres-arias diff --git a/analyses/0010-etcd/README.md b/analyses/0010-etcd/README.md index d877f01..cb3ff7a 100644 --- a/analyses/0010-etcd/README.md +++ b/analyses/0010-etcd/README.md @@ -3,6 +3,10 @@ title: etcd TechDocs Analysis tags: etcd --- -- [etcd Doc Analysis](etcd-analysis.md) - Analyzes the existing etcd documentation and provides recommendations. -- [etcd Implementation](etcd-implementation.md) - Provides detailed and actionable recommendations, intended to be worked on as GitHub issues. -- [etcd Issues](etcd-issues.md) - A list of documentation improvements derived from etcd Implementation, entered as issues in the [etcd-io/website repo](https://github.com/etcd-io/website/issues/766). +- [etcd Doc Analysis](etcd-analysis.md) - Analyzes the existing etcd + documentation and provides recommendations. +- [etcd Implementation](etcd-implementation.md) - Provides detailed and + actionable recommendations, intended to be worked on as GitHub issues. +- [etcd Issues](etcd-issues.md) - A list of documentation improvements derived + from etcd Implementation, entered as issues in the + [etcd-io/website repo](https://github.com/etcd-io/website/issues/766). diff --git a/analyses/0010-etcd/etcd-analysis.md b/analyses/0010-etcd/etcd-analysis.md index e4519e4..18824fe 100644 --- a/analyses/0010-etcd/etcd-analysis.md +++ b/analyses/0010-etcd/etcd-analysis.md @@ -8,27 +8,44 @@ author: Dave Welsch (@dwelsch-esi) # Introduction -This document analyzes the effectiveness and completeness of the [etcd][etcd-io] 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 [etcd][etcd-io] +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. +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 was written to analyze the current state of etcd documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. The companion document, etcd-impementation.md, outlines an actionable plan for improvement. +This document was written to analyze the current state of etcd documentation. It +aims to provide project leaders with an informed understanding of potential +problems in current project documentation. The companion document, +etcd-impementation.md, outlines an actionable plan for improvement. This document: - Analyzes the current etcd technical documentation and website - Compares existing documentation against the CNCF’s standards -- Recommends a program of key improvements with the largest return on investment. The companion document, etcd-impementation.md, provides specific actionable suggestions and recommendations for overall organization and presentation of documentation +- Recommends a program of key improvements with the largest return on + investment. The companion document, etcd-impementation.md, provides specific + actionable suggestions and recommendations for overall organization and + presentation of documentation ## Scope of analysis -The documentation discussed here includes the entire contents of the website (which contains the technical docs), as well as documentation for contributors and users on the etcd GitHub repository. +The documentation discussed here includes the entire contents of the website +(which contains the technical docs), as well as documentation for contributors +and users on the etcd GitHub repository. -The etcd website and documentation are written in Markdown and are compiled using the Hugo static site generator with the Docsy theme and served from the Netlify platform. The site's code is stored on the etcd GitHub repo. +The etcd website and documentation are written in Markdown and are compiled +using the Hugo static site generator with the Docsy theme and served from the +Netlify platform. The site's code is stored on the etcd GitHub repo. **In scope:** + - Website: https://etcd.io - Documentation: https://etcd.io/docs - Website repo: https://github.com/etcd-io/website @@ -36,75 +53,109 @@ The etcd website and documentation are written in Markdown and are compiled usin - Demo server: http://play.etcd.io **Out of scope:** -- Other etcd repos: https://github.com/etcd-io/* +- Other etcd repos: https://github.com/etcd-io/* ## How this document is organized -This document is divided into three sections that represent three major areas of concern: +This document is divided into three sections that represent three major areas of +concern: -- **Project documentation:** concerns documentation for users of the etcd software, aimed at people who intend to use it -- **Contributor documentation:** concerns documentation for new and existing contributors to the etcd OSS project -- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability +- **Project documentation:** concerns documentation for users of the etcd + software, aimed at people who intend to use it +- **Contributor documentation:** concerns documentation for new and existing + contributors to the etcd OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability -Each section begins with summary ratings based on a rubric with appropriate [criteria][cncf-doc-criteria] for the section, then proceeds to: -- **Comments**: observations about the existing documentation, with a focus on how it does or does not help etcd users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness of the documentation. +Each section begins with summary ratings based on a rubric with appropriate +[criteria][cncf-doc-criteria] for the section, then proceeds to: -An accompanying document, [etcd-implementation.md][implementation-doc], 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 should be tracked as a series of Github [issues][etcd-issues]. +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help etcd users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. +An accompanying document, [etcd-implementation.md][implementation-doc], 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 should be tracked as a series of Github +[issues][etcd-issues]. ## How to use this document -Readers interested only in actionable improvements should skip this document and read [etcd-implementation.md][implementation-doc]. +Readers interested only in actionable improvements should skip this document and +read [etcd-implementation.md][implementation-doc]. -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: +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][proj-doc] - [Contributor documentation][contributor-doc] - [Website and documentation infrrastructure][website] -Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [Criteria][cncf-doc-criteria] specification. - +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [Criteria][cncf-doc-criteria] specification. ### 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-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. - +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-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. # Project documentation -etcd is a **graduated** project of CNCF. This means that the project should have [*very high*][cncf-doc-criteria] standards for documentation. - -| Criterion | Rating (1-5) | -| --- | --- | -| Information architecture | 2 - needs improvement | -| New user content | 2 - needs improvement | -| Content maintainability | 3 - meets standards | -| Content creation processes | 2 - needs improvement | -| Inclusive language | 2 - needs improvement | +etcd is a **graduated** project of CNCF. This means that the project should have +[_very high_][cncf-doc-criteria] standards for documentation. +| Criterion | Rating (1-5) | +| -------------------------- | --------------------- | +| Information architecture | 2 - needs improvement | +| New user content | 2 - needs improvement | +| Content maintainability | 3 - meets standards | +| Content creation processes | 2 - needs improvement | +| Inclusive language | 2 - needs improvement | ## Comments -Much of the documentation seems as if it hasn't been reviewed and updated for a while. +Much of the documentation seems as if it hasn't been reviewed and updated for a +while. -The following sections contain brief assessments of each element of the Project Documentation rubric. +The following sections contain brief assessments of each element of the Project +Documentation rubric. ### Information architecture -There is **high-level conceptual** and design content, but it is hard to find. Most of it is in a *Learning* section, which is not a conventional label for a system overview. +There is **high-level conceptual** and design content, but it is hard to find. +Most of it is in a _Learning_ section, which is not a conventional label for a +system overview. -The *Learning* section, right before *Developer guide* in the ToC, is a catch-all for a lot of different types of information: +The _Learning_ section, right before _Developer guide_ in the ToC, is a +catch-all for a lot of different types of information: -- An architectural overview (explanations of how etcd's client and resiliency architectures work). -- Adoption decision information, in *etcd versus other key-value stores*. This information needs updating. +- An architectural overview (explanations of how etcd's client and resiliency + architectures work). +- Adoption decision information, in _etcd versus other key-value stores_. This + information needs updating. - An overview of the gRPC-based API. - A glossary. -The documentation is not **feature complete**. There are some **undocumented tasks** associated with key features. For example, Kubernetes and Linux installations are not fully documented. The [Authentication][docs-authentication] page is a stub containing only a CLI example. +The documentation is not **feature complete**. There are some **undocumented +tasks** associated with key features. For example, Kubernetes and Linux +installations are not fully documented. The +[Authentication][docs-authentication] page is a stub containing only a CLI +example. -The documentation contains **instructions** for various features. These instructions include: +The documentation contains **instructions** for various features. These +instructions include: - A Quickstart guide - Installation instructions @@ -114,52 +165,113 @@ The documentation contains **instructions** for various features. These instruct ... and other tasks and procedures. -The documentation contains an adequate introduction and overview, but these are buried in the doc and difficult to find. The adoption path needs more focus and to be split out by user role. For example, "Getting started" should be different for a developer setting up a development server vs. an admin setting up a production server. - -The **"happy path"** for etcd is not a simple procedure and, again, varies by user role. However, I believe that there is sufficient documentation of the most common use cases (configure and run an HA server cluster; set and get key-value pairs via an API from an application) to argue that it is documented. Exception: The Kubernetes and Linux installation instructions noted above. Also, procedures for Operators using etcd with Kubernetes (a distinct user role) are a separate path and are at least partially covered in the Kubernetes documentation. - -Task and tutorial content are **clearly named according to user goals**. Using "-ing" verb forms instead of "How to ..." would make headings easier to navigate. - -Tutorials contain large animated graphics of command line activity. These are distracting and degrade the usability of the instructions. - -**Escalation paths** are clearly described in [Reporting bugs](https://etcd.io/docs/v3.5/reporting_bugs/) and [Triage][etcdio-triage]. - -The product provides a [**reference for the API**](https://etcd.io/docs/v3.5/learning/api/). The documentation also references many language-specific libraries used to integrate with etcd. - -Documentation content **is versioned**. The current documentation set is for the stable 3.5 release of etcd. The site also contains a draft version of documentation for the 3.6 release labeled "v3.6-DRAFT". The site lists several versions of the documentation for down-level releases. These could be archived. - -There are references to previous releases in the documentation. Most of these should probably be removed. - -Benchmarks for down-level versions are available in the current documentation. It's not clear why these old benchmarks haven't been removed from the documentation. - -There is an example **installation** on the [etcd Play](http://play.etcd.io/install) server that presents "an example workflow to install and deploy etcd." This page consists of a form containing parameters (with no explanation of each parameter other than the label) followed by a CLI script that varies depending on the installation type you choose. Presumably you're supposed to run the script to do the install, but there are no clear task instructions at all. It's not clear how this is useful. Novice users will have a hard time with this. Also, why is this information on the demo server at all? Users should be referred to an installation procedure in the documentation. If this represents a separate, automated installation workflow it should be offered as a procedure in the user doc. +The documentation contains an adequate introduction and overview, but these are +buried in the doc and difficult to find. The adoption path needs more focus and +to be split out by user role. For example, "Getting started" should be different +for a developer setting up a development server vs. an admin setting up a +production server. + +The **"happy path"** for etcd is not a simple procedure and, again, varies by +user role. However, I believe that there is sufficient documentation of the most +common use cases (configure and run an HA server cluster; set and get key-value +pairs via an API from an application) to argue that it is documented. Exception: +The Kubernetes and Linux installation instructions noted above. Also, procedures +for Operators using etcd with Kubernetes (a distinct user role) are a separate +path and are at least partially covered in the Kubernetes documentation. + +Task and tutorial content are **clearly named according to user goals**. Using +"-ing" verb forms instead of "How to ..." would make headings easier to +navigate. + +Tutorials contain large animated graphics of command line activity. These are +distracting and degrade the usability of the instructions. + +**Escalation paths** are clearly described in +[Reporting bugs](https://etcd.io/docs/v3.5/reporting_bugs/) and +[Triage][etcdio-triage]. + +The product provides a +[**reference for the API**](https://etcd.io/docs/v3.5/learning/api/). The +documentation also references many language-specific libraries used to integrate +with etcd. + +Documentation content **is versioned**. The current documentation set is for the +stable 3.5 release of etcd. The site also contains a draft version of +documentation for the 3.6 release labeled "v3.6-DRAFT". The site lists several +versions of the documentation for down-level releases. These could be archived. + +There are references to previous releases in the documentation. Most of these +should probably be removed. + +Benchmarks for down-level versions are available in the current documentation. +It's not clear why these old benchmarks haven't been removed from the +documentation. + +There is an example **installation** on the +[etcd Play](http://play.etcd.io/install) server that presents "an example +workflow to install and deploy etcd." This page consists of a form containing +parameters (with no explanation of each parameter other than the label) followed +by a CLI script that varies depending on the installation type you choose. +Presumably you're supposed to run the script to do the install, but there are no +clear task instructions at all. It's not clear how this is useful. Novice users +will have a hard time with this. Also, why is this information on the demo +server at all? Users should be referred to an installation procedure in the +documentation. If this represents a separate, automated installation workflow it +should be offered as a procedure in the user doc. ### New user content -There is a single paragraph on the [website][etcd-io] landing page with a "Learn more" link that goes to the current documetation table of contents (ToC). It would be better to link to an overview page that laid out learning paths for different users ("Start here"). - -There are **install** and **quick start** entries in the technical documentation ToC. These are good starting points but could be refined. User roles are not addressed. - -The **installation** page gives step-by-step instructions for installing from binaries, from source, and using a package manager. Installation as part of a Kubernetes installation is also described on the page, but there is a placeholder under the heading "Installation as part of Kubernetes installation". I understand that etcd installation with Kubernetes depends on how you install Kubernetes, and that in some cases it's automatic and/or documented in the Kubernetes tech doc. In any case, there should be a discussion of the options and links to the relevant Kubernetes docs. Linux installation is also "TBD", which seems like a big omission. - -Package manager installation is documented (but not recommended) for Linux and MacOS. **Other OSes** are alluded to but not documented. Supported platforms are documented in the [Operations guide](https://etcd.io/docs/v3.5/op-guide/supported-platform/). - -The *Quickstart* section lists suggested next steps in a *What's next?* heading. However, there is no such section on the *Installation* page, and in neither location is a clear **workflow path** delineated. - -There is no **new user signpost** in the documentation. The closest equivalent is the *Quickstart* section, but the Quickstart does not differentiate among user roles (Developer? Operator? Evaluator trying to decide whether to adopt?). - -The examples in the installation, configuration, and other documentation provide ample code to **copy-paste**. - -There are instructions for installing and getting started in the etcd-io/etcd [README][etcd-readme]. It would be preferable to point new users and contributors to the documentation straightaway. - +There is a single paragraph on the [website][etcd-io] landing page with a "Learn +more" link that goes to the current documetation table of contents (ToC). It +would be better to link to an overview page that laid out learning paths for +different users ("Start here"). + +There are **install** and **quick start** entries in the technical documentation +ToC. These are good starting points but could be refined. User roles are not +addressed. + +The **installation** page gives step-by-step instructions for installing from +binaries, from source, and using a package manager. Installation as part of a +Kubernetes installation is also described on the page, but there is a +placeholder under the heading "Installation as part of Kubernetes installation". +I understand that etcd installation with Kubernetes depends on how you install +Kubernetes, and that in some cases it's automatic and/or documented in the +Kubernetes tech doc. In any case, there should be a discussion of the options +and links to the relevant Kubernetes docs. Linux installation is also "TBD", +which seems like a big omission. + +Package manager installation is documented (but not recommended) for Linux and +MacOS. **Other OSes** are alluded to but not documented. Supported platforms are +documented in the +[Operations guide](https://etcd.io/docs/v3.5/op-guide/supported-platform/). + +The _Quickstart_ section lists suggested next steps in a _What's next?_ heading. +However, there is no such section on the _Installation_ page, and in neither +location is a clear **workflow path** delineated. + +There is no **new user signpost** in the documentation. The closest equivalent +is the _Quickstart_ section, but the Quickstart does not differentiate among +user roles (Developer? Operator? Evaluator trying to decide whether to adopt?). + +The examples in the installation, configuration, and other documentation provide +ample code to **copy-paste**. + +There are instructions for installing and getting started in the etcd-io/etcd +[README][etcd-readme]. It would be preferable to point new users and +contributors to the documentation straightaway. ### Content maintainability & site mechanics -Documentation content is **versioned** with the software. Versions are maintained in separate **directories** in the website content repo. +Documentation content is **versioned** with the software. Versions are +maintained in separate **directories** in the website content repo. -Documentation is fully **searchable**. Searches are apparently limited to the current (stable) software version, though searching for "upgrade" lists instructions for upgrading 3.3 -> 3.4 in the v3.4 doc, 3.2 -> 3.3 in the 3.3 doc, and so on. Search also returns blog entries. +Documentation is fully **searchable**. Searches are apparently limited to the +current (stable) software version, though searching for "upgrade" lists +instructions for upgrading 3.3 -> 3.4 in the v3.4 doc, 3.2 -> 3.3 in the 3.3 +doc, and so on. Search also returns blog entries. -There are links to docs for previous releases in some of the 3.5 documentation files: +There are links to docs for previous releases in some of the 3.5 documentation +files: - dev-internal/discovery_protocol.md - op-guide/runtime-configuration.md @@ -167,55 +279,91 @@ There are links to docs for previous releases in some of the 3.5 documentation f - metrics.md - dev-guide/discovery_protocol.md -The website content folder contains a **language-specific directory** in its hierarchy, implying a mechanism for doing **internationalization** if necessary. There do not appear to be plans to translate the documentation from English. - -There is a Github issue label (`area/documentation`) for **documentation issues**. +The website content folder contains a **language-specific directory** in its +hierarchy, implying a mechanism for doing **internationalization** if necessary. +There do not appear to be plans to translate the documentation from English. +There is a Github issue label (`area/documentation`) for **documentation +issues**. ### Content creation processes -There are instructions for contributing to documentation and for **releasing a new version** of the etcd **documentation** in the `README.md` file in the [website repo](https://github.com/etcd-io/website/blob/main/README.md). The instructions are out of date. See issues #383, 405, 406. - -The website has a [**list of maintainers and reviewers**](https://github.com/etcd-io/website/blob/main/OWNERS). Those maintainer **responsible for approving** documentation PRs are listed as "approvers". +There are instructions for contributing to documentation and for **releasing a +new version** of the etcd **documentation** in the `README.md` file in the +[website repo](https://github.com/etcd-io/website/blob/main/README.md). The +instructions are out of date. See issues #383, 405, 406. -The website repo [README](../../README.md) is out of date. For example, instructions for building the website state that the local build starts the server on `localhost:8888`. It's actually `localhost:1313`. +The website has a +[**list of maintainers and reviewers**](https://github.com/etcd-io/website/blob/main/OWNERS). +Those maintainer **responsible for approving** documentation PRs are listed as +"approvers". +The website repo [README](../../README.md) is out of date. For example, +instructions for building the website state that the local build starts the +server on `localhost:8888`. It's actually `localhost:1313`. ### Inclusive language -Language is mostly inclusive. For example, the neutral terms "Leader" and "Follower" are used to describe server failover roles. +Language is mostly inclusive. For example, the neutral terms "Leader" and +"Follower" are used to describe server failover roles. -However, there are isolated instances of somewhat **non-inclusive language**. For example: +However, there are isolated instances of somewhat **non-inclusive language**. +For example: -- [installation check][install-check]: contains "sanity check", a term designated "Strongly Consider Replacing" by the [Inclusive Naming Initiative][inclusive-naming]. -- There is some use of language like "easy", "simple", and "just [take an action]"; for example, "Creating a user is as easy as" in [Role-based access control](https://etcd.io/docs/v3.5/op-guide/authentication/rbac/). +- [installation check][install-check]: contains "sanity check", a term + designated "Strongly Consider Replacing" by the [Inclusive Naming + Initiative][inclusive-naming]. +- There is some use of language like "easy", "simple", and "just [take an + action]"; for example, "Creating a user is as easy as" in + [Role-based access control](https://etcd.io/docs/v3.5/op-guide/authentication/rbac/). ## Recommendations ### Information architecture Reorganize the table of contents (ToC) to separate three types of information: -- **Conceptual**: Information that is necessary to understanding but not directly usable. The main bodies of conceptual information are architecture and system overviews. -- **Instructional**: How to complete tasks necessary to use the software (this includes programming and integration using APIs). Organize instructional material by user role: for etcd, the two main user roles seem to be 1) developers, and 2) operators or admins responsible for running and maintaining etcd server instances. -- **Reference**: The details of CLI commands, API metehods and objects, system configuration options, and other information that needs to be looked up in the course of performning a task. - -For an excellent and very literal example of this approach, see the [Kubernetes documentation][k8s-doc]. - -Much of the conceptual information about etcd is in the "Learning" section. Rename this section and organize it into a primer on the etcd architecture. Move non-conceptual information elsewhere. -Fill in missing instructional documentation. Most notably, write (or link to) instructions for installing on Kubernetes and Linux, and on using Authentication. +- **Conceptual**: Information that is necessary to understanding but not + directly usable. The main bodies of conceptual information are architecture + and system overviews. +- **Instructional**: How to complete tasks necessary to use the software (this + includes programming and integration using APIs). Organize instructional + material by user role: for etcd, the two main user roles seem to be 1) + developers, and 2) operators or admins responsible for running and maintaining + etcd server instances. +- **Reference**: The details of CLI commands, API metehods and objects, system + configuration options, and other information that needs to be looked up in the + course of performning a task. + +For an excellent and very literal example of this approach, see the [Kubernetes +documentation][k8s-doc]. + +Much of the conceptual information about etcd is in the "Learning" section. +Rename this section and organize it into a primer on the etcd architecture. Move +non-conceptual information elsewhere. + +Fill in missing instructional documentation. Most notably, write (or link to) +instructions for installing on Kubernetes and Linux, and on using +Authentication. Use "-ing" verb forms instead of "How to ..." as headings for procedures. -Break procedures out to one per page. For example, instead of every installation case being on one page, create a navigation page explaining the use case for each installation and link to a page whose sole content is step-by-step installation instructions. +Break procedures out to one per page. For example, instead of every installation +case being on one page, create a navigation page explaining the use case for +each installation and link to a page whose sole content is step-by-step +installation instructions. -Replace animated GIFs of command line activity with static listings of the outputs that can be studied and copy/pasted. +Replace animated GIFs of command line activity with static listings of the +outputs that can be studied and copy/pasted. -Create a Troubleshooting page that helps with common problems. Link to Slack channels and issue and PR submission instructions in the GitHub repo in case more help is needed. +Create a Troubleshooting page that helps with common problems. Link to Slack +channels and issue and PR submission instructions in the GitHub repo in case +more help is needed. Consider archiving old versions of the documentation to reduce clutter. -Remove references to previous releases in the documentation. These references are in the following 3.5 documentation files: +Remove references to previous releases in the documentation. These references +are in the following 3.5 documentation files: - learning/design-learner.md - learning/design-client.md @@ -224,41 +372,59 @@ Remove references to previous releases in the documentation. These references ar - op-guide/clustering.md - op-guide/authentication/rbac.md - op-guide/maintenance.md -- benchmarks/* -- upgrades/* +- benchmarks/\* +- upgrades/\* - dev-guide/api_grpc_gateway.md - dev-guide/interacting_v3.md - dev-guide/grpc_naming.md -In general, confine release-specific discussion to the Release Notes. +In general, confine release-specific discussion to the Release Notes. -Remove benchmarks for down-level versions in the current documentation if they're no longer relevant. +Remove benchmarks for down-level versions in the current documentation if +they're no longer relevant. -Consider removing the installation example from the [etcd Play](http://play.etcd.io/install) server and pointing the user to the documentation's installation instructions. +Consider removing the installation example from the +[etcd Play](http://play.etcd.io/install) server and pointing the user to the +documentation's installation instructions. ### New user content -Point "Learn more" links to a "Start here" page that provides orientation and sets out paths for different user roles. For example, the Developer path should provide instructions for: +Point "Learn more" links to a "Start here" page that provides orientation and +sets out paths for different user roles. For example, the Developer path should +provide instructions for: 1. Installing a local server. 2. Setting up an environment and testing the server using the CLI. 3. Getting started programming with an API. -Write step-by-step instructions for all installation cases. (Or, in the case of a Kubernetes Operator user role, links to relevant Kubernetes docs.) Clearly describe what each case is for; especially distinguish between development and production installations. +Write step-by-step instructions for all installation cases. (Or, in the case of +a Kubernetes Operator user role, links to relevant Kubernetes docs.) Clearly +describe what each case is for; especially distinguish between development and +production installations. + +Revise the Quick Start guide to indicate which user role it's for: -Revise the Quick Start guide to indicate which user role it's for: - developer, - etcd standalone operator/admin, - Kubernetes operator/admin, or - adoption decision maker -This might require the Quick Start guide to have multiple paths or be split into two or more guides. Again, Kubernetes operators can be referred to the Kubernetes documentation if it substantively covers the etcd topics. Focus the options in the "What's next?" section to point to a few (two or three) learning paths for specific persona use cases. +This might require the Quick Start guide to have multiple paths or be split into +two or more guides. Again, Kubernetes operators can be referred to the +Kubernetes documentation if it substantively covers the etcd topics. Focus the +options in the "What's next?" section to point to a few (two or three) learning +paths for specific persona use cases. -Remove getting-started instructions from the main GitHub repo README and instead point the user to the documentation. +Remove getting-started instructions from the main GitHub repo README and instead +point the user to the documentation. ### Content maintainability & site mechanics -Remove links to documentation for previous releases from the current documentation version. Going forward, write doc for each release without referring to previous ("In 3.2 this feature was changed ...") or future ("We plan to upgrade this in the next release ..."). Such comments should go only in release notes. +Remove links to documentation for previous releases from the current +documentation version. Going forward, write doc for each release without +referring to previous ("In 3.2 this feature was changed ...") or future ("We +plan to upgrade this in the next release ..."). Such comments should go only in +release notes. References to previous versions are in the following 3.5 documentation files: @@ -268,209 +434,243 @@ References to previous versions are in the following 3.5 documentation files: - metrics.md - dev-guide/discovery_protocol.md - ### Content creation processes Update the content creation instructions in the website README file. -Move issue and PR submission guidelines from the documentation ("Triage") to the Github repo. Link to these guidelines from a Troubleshooting section in the docs. - +Move issue and PR submission guidelines from the documentation ("Triage") to the +Github repo. Link to these guidelines from a Troubleshooting section in the +docs. ### Inclusive language -Audit the documentation for non-inclusive language. See the [Inclusive Naming Initiative](https://inclusivenaming.org/) website. - +Audit the documentation for non-inclusive language. See the +[Inclusive Naming Initiative](https://inclusivenaming.org/) website. # Contributor documentation -etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for contributor documentation. - -| Criterion | Rating (1-5) | -| --- | --- | -| Communication methods documented | 3 - meets standards | -| Beginner friendly issue backlog | 3 - meets standards | -| “New contributor” getting started content | 3 - meets standards | -| Project governance documentation | 4 - meets or exceeds standards | +etcd is a **graduated** project of CNCF. This means that the project should have +[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) +standards for contributor documentation. +| Criterion | Rating (1-5) | +| ----------------------------------------- | ------------------------------ | +| Communication methods documented | 3 - meets standards | +| Beginner friendly issue backlog | 3 - meets standards | +| “New contributor” getting started content | 3 - meets standards | +| Project governance documentation | 4 - meets or exceeds standards | ## Comments ### Communication methods documented -**Communication channels** include a Google Group and Twitter, and are documented on the [Community][etcd-community] page. +**Communication channels** include a Google Group and Twitter, and are +documented on the [Community][etcd-community] page. -There is a link to the **GitHub** repository in the website footer. There are links on the Community page to the [**GitHub** Discussions][etcd-git-discuss] page and the [How to contribute][etcd-howtocontrib]. +There is a link to the **GitHub** repository in the website footer. There are +links on the Community page to the [**GitHub** Discussions][etcd-git-discuss] +page and the [How to contribute][etcd-howtocontrib]. -The Community page has a schedule, minutes, and recordings of the project's biweekly **meetings**. +The Community page has a schedule, minutes, and recordings of the project's +biweekly **meetings**. -There does not seem to be any periodic broadcast communication like a **mailing list**. - -[Triage][etcdio-triage] contains instructions for dealing with issues and PRs in the etcd repo. These should be in the repo itself, with a pointer from the documentation troubleshooting section. +There does not seem to be any periodic broadcast communication like a **mailing +list**. +[Triage][etcdio-triage] contains instructions for dealing with issues and PRs in +the etcd repo. These should be in the repo itself, with a pointer from the +documentation troubleshooting section. ### Beginner friendly issue backlog -There is a **good first issue** label. Issues are generally **well documented** by submitters and discussed in the Issues forum. There is a label (`area/documentation`) for **documentation issues**. - -There are a number of **stale issues**. Here's a summary of the age of open issues for the etcd main repo at the time of this writing: +There is a **good first issue** label. Issues are generally **well documented** +by submitters and discussed in the Issues forum. There is a label +(`area/documentation`) for **documentation issues**. +There are a number of **stale issues**. Here's a summary of the age of open +issues for the etcd main repo at the time of this writing: -| Age | Count | Histogram | -| --- | ----- | --- | -| < 1 mo | 22 | **** | -| 1 mo - 2 mo | 10 | ** | -| 2 mo - 3 mo | 10 | ** | -| 3 mo - 6 mo | 38 | ******* | -| 6 mo - 12 mo | 40 | ******** | -| > 12 mo | 52 | *********** | - +| Age | Count | Histogram | +| ------------ | ----- | ---------------------- | +| < 1 mo | 22 | \*\*\*\* | +| 1 mo - 2 mo | 10 | \*\* | +| 2 mo - 3 mo | 10 | \*\* | +| 3 mo - 6 mo | 38 | \*\*\*\*\*\*\* | +| 6 mo - 12 mo | 40 | \*\*\*\*\*\*\*\* | +| > 12 mo | 52 | \*\*\*\*\*\*\*\*\*\*\* | ### New contributor getting started content -There is a [**Community**][etcd-community] page on the etcd website. There is no dedicated **"first-contributor"** document, but there are multiple resources and pointers in the general contributor instructions. New contributors should have minimal difficulty **finding help** if they need it. - +There is a [**Community**][etcd-community] page on the etcd website. There is no +dedicated **"first-contributor"** document, but there are multiple resources and +pointers in the general contributor instructions. New contributors should have +minimal difficulty **finding help** if they need it. ### Project governance documentation [**Project goverance**][etcd-govern] is clearly documented. - ## Recommendations - ### Communication methods documented -Move the information from the [Triage][etcdio-triage] doc section into the repo itself, with pointers from the documentation Troubleshooting guide. - +Move the information from the [Triage][etcdio-triage] doc section into the repo +itself, with pointers from the documentation Troubleshooting guide. ### Beginner friendly issue backlog No recommendations. - ### New contributor getting started content -Consider creating a conspicuous "First contributor start here" document in the repo, with links to the other contributor resources. - +Consider creating a conspicuous "First contributor start here" document in the +repo, with links to the other contributor resources. ### Project governance documentation No recommnendations. - # Website -etcd is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. - -| Criterion | Rating (1-5) | -| --- | --- | -| Single-source for all files | 5 - exemplary | -| Meets min website req. (for maturity level) | 2 - needs improvement | -| Usability, accessibility, and design | 3 - meets standards | -| Branding and design | 4 - meets or exceeds standards | -| Case studies/social proof | 3 - meets standards | -| SEO, Analytics, and site-local search | 5 - exemplary | -| Maintenance planning | 5 - exemplary | -| A11y plan & implementation | 4 - meets or exceeds standards | -| Mobile-first plan & impl. | 3 - meets standards | -| HTTPS access & HTTP redirect | 4 - meets or exceeds standards | -| Google Analytics 4 for production only | 5 - exemplary | -| Indexing allowed for production server only | 5 - exemplary | -| Intra-site / local search | 5 - exemplary | -| Account custodians are documented | 4 - meets or exceeds standards | - +etcd is a **graduated** project of CNCF. This means that the project should have +[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) +standards for documentation. + +| Criterion | Rating (1-5) | +| ------------------------------------------- | ------------------------------ | +| Single-source for all files | 5 - exemplary | +| Meets min website req. (for maturity level) | 2 - needs improvement | +| Usability, accessibility, and design | 3 - meets standards | +| Branding and design | 4 - meets or exceeds standards | +| Case studies/social proof | 3 - meets standards | +| SEO, Analytics, and site-local search | 5 - exemplary | +| Maintenance planning | 5 - exemplary | +| A11y plan & implementation | 4 - meets or exceeds standards | +| Mobile-first plan & impl. | 3 - meets standards | +| HTTPS access & HTTP redirect | 4 - meets or exceeds standards | +| Google Analytics 4 for production only | 5 - exemplary | +| Indexing allowed for production server only | 5 - exemplary | +| Intra-site / local search | 5 - exemplary | +| Account custodians are documented | 4 - meets or exceeds standards | ## Comments ### Single-source requirement -The website has its own GitHub **repository**. The website repo contains the documentation and is separated from the project source code. +The website has its own GitHub **repository**. The website repo contains the +documentation and is separated from the project source code. -**Contributor documentation** is contained in the [main code repo][github-etcd-etcd] in well labeled Markdown files. +**Contributor documentation** is contained in the [main code +repo][github-etcd-etcd] in well labeled Markdown files. ### Minimal website requirements -Except for archived projects, requirements are cumulative through project maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. - -Listed and acknowledged below are the (cumulative) _minimal_ website requirements for projects based on their [maturity level][website-min-reqs]: sandbox, incubating, graduated and archived. - -| Maturity | Requirement | Met? | -| --- | --- | --- | -| Sandbox | Majority of [Website guidelines][website-guidelines] satisfied | Yes | -| Sandbox | [Docs assessment][assess-howto] [submitting a request][cncf-servicedesk] completed. | Yes | -| Sandbox | **Project documentation** exists – somewhere. It is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website. (May still be in the project GitHub repo, for example.) | Yes | -| Incubating | All [Website guidelines][website-guidelines] satisfied | No - no DCO some repos, incl. doc | -| Incubating | Request docs (re-)assessment through CNCF [service desk][cncf-servicedesk] | Yes | -| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | No | -| Incubating | **Project doc**: Hosted directly | Yes | -| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | Yes | -| Graduated | [Docs assessment][assess-howto]: all assessment follow-through actions are complete | No | -| Graduated | **Project doc** fully addresses needs of key stakeholders | No | -| Archived | The website repo is in an [archived state][archiving-repo] | n/a | -| Archived | Archived status of the project is obvious to site visitors | n/a | -| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a | +Except for archived projects, requirements are cumulative through project +maturity levels so, for example, incubating projects must satisfy the +requirements for sandbox projects. + +Listed and acknowledged below are the (cumulative) _minimal_ website +requirements for projects based on their [maturity level][website-min-reqs]: +sandbox, incubating, graduated and archived. + +| Maturity | Requirement | Met? | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| Sandbox | Majority of [Website guidelines][website-guidelines] satisfied | Yes | +| Sandbox | [Docs assessment][assess-howto] [submitting a request][cncf-servicedesk] completed. | Yes | +| Sandbox | **Project documentation** exists – somewhere. It is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website. (May still be in the project GitHub repo, for example.) | Yes | +| Incubating | All [Website guidelines][website-guidelines] satisfied | No - no DCO some repos, incl. doc | +| Incubating | Request docs (re-)assessment through CNCF [service desk][cncf-servicedesk] | Yes | +| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | No | +| Incubating | **Project doc**: Hosted directly | Yes | +| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | Yes | +| Graduated | [Docs assessment][assess-howto]: all assessment follow-through actions are complete | No | +| Graduated | **Project doc** fully addresses needs of key stakeholders | No | +| Archived | The website repo is in an [archived state][archiving-repo] | n/a | +| Archived | Archived status of the project is obvious to site visitors | n/a | +| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a | ### Usability, accessibility and devices -The site is **usable from mobile**. **Doc pages are readable**. Features such as **search** and **top-nav** work; the **in-page TOC** is missing on a small phone screen. A **mobile-first design** does not make sense for this project. - -Most, but not all **color contrasts** seem significant enough for color-impaired readers. For example, there are some light-blue on dark-blue labels on buttons on the landing page. Basic **website features**, including navigation, can be done via **keyboard**. Unknown whether **text-to-speech** is a good user experience for listeners. +The site is **usable from mobile**. **Doc pages are readable**. Features such as +**search** and **top-nav** work; the **in-page TOC** is missing on a small phone +screen. A **mobile-first design** does not make sense for this project. +Most, but not all **color contrasts** seem significant enough for color-impaired +readers. For example, there are some light-blue on dark-blue labels on buttons +on the landing page. Basic **website features**, including navigation, can be +done via **keyboard**. Unknown whether **text-to-speech** is a good user +experience for listeners. ### Branding and design -The website and documentation carry an **easily recognizable brand** for the project based on logo, color scheme, and template layout. The brand is used **consistently** on the site. The text is easily **readable**. - +The website and documentation carry an **easily recognizable brand** for the +project based on logo, color scheme, and template layout. The brand is used +**consistently** on the site. The text is easily **readable**. ### Case studies/social proof -The landing page lists a tiny **"logo wall"** of four "Used by" organizations, though given that one of those organizations is Kubernetes, this seems adequate. The site does not offer **case studies**. Instead, logos link to the organizations' home pages. No **user testimonials** are available. +The landing page lists a tiny **"logo wall"** of four "Used by" organizations, +though given that one of those organizations is Kubernetes, this seems adequate. +The site does not offer **case studies**. Instead, logos link to the +organizations' home pages. No **user testimonials** are available. -There is a **project blog**, but it is not a site of active discussion; blog post frequency is annual or less. There do not seem to be any **community talks** available on the website. The YouTube channel contains videos of the bi-weekly meetings. - -There is an ADOPTERS.md file in the etcd-io/etcd repository that lists a number of production users of etcd. Each entry in the file gives some details about the production installation, including when it was launched, the cluster size, what application is using etcd, and the cloud environment. The list of production users in this file is probably not exhaustive. +There is a **project blog**, but it is not a site of active discussion; blog +post frequency is annual or less. There do not seem to be any **community +talks** available on the website. The YouTube channel contains videos of the +bi-weekly meetings. +There is an ADOPTERS.md file in the etcd-io/etcd repository that lists a number +of production users of etcd. Each entry in the file gives some details about the +production installation, including when it was launched, the cluster size, what +application is using etcd, and the cloud environment. The list of production +users in this file is probably not exhaustive. ### SEO, Analytics and site-local search -The website has site-wide search, GA4 enabled, and well indexed on popular search engines; matches perfectly to our criteria. +The website has site-wide search, GA4 enabled, and well indexed on popular +search engines; matches perfectly to our criteria. **Analytics:** -* Analytics is enabled for production site. -* Analytics is disabled for all other deploys. -* Project analytics has been migrated to GA4. -* Page-not-found (404) reports can be easily be generated from the site analytics. + +- Analytics is enabled for production site. +- Analytics is disabled for all other deploys. +- Project analytics has been migrated to GA4. +- Page-not-found (404) reports can be easily be generated from the site + analytics. **Indexing and Search:** -* Production site is well indexed. -* Local intra-site search available from the website. + +- Production site is well indexed. +- Local intra-site search available from the website. **Account custodians** -* Account custodians are not clearly documented. -### Maintenance planning +- Account custodians are not clearly documented. -The website uses Hugo and Docsy, which are the recommended **website tooling** for CNCF projects. +### Maintenance planning +The website uses Hugo and Docsy, which are the recommended **website tooling** +for CNCF projects. -Web maintainers cultivated? Maintainers are actively cultivated within the community. +Web maintainers cultivated? Maintainers are actively cultivated within the +community. The website builds in **reasonable time** on a desktop computer. -Site maintainers have **adequate permissions** to update the website. - -Maintainers of the [website repository][website-repo] are adequately documented in the OWNERS file in the repo. Approvers and reviewers are listed. +Site maintainers have **adequate permissions** to update the website. +Maintainers of the [website repository][website-repo] are adequately documented +in the OWNERS file in the repo. Approvers and reviewers are listed. ### Other -The website is accessible via **HTTPS**. Requests using **HTTP** are properly redirected to the **HTTPS** URLs. +The website is accessible via **HTTPS**. Requests using **HTTP** are properly +redirected to the **HTTPS** URLs. The [demo server][demo-server] uses unsecured HTTP. ## Recommendations - ### Single-source requirement No recommendations. @@ -479,43 +679,39 @@ No recommendations. Update website to include DCO or other source validation. -Identify stakeholders (user roles). Ensure that instructions exist in the documentation for all major use cases for each stakeholder. - +Identify stakeholders (user roles). Ensure that instructions exist in the +documentation for all major use cases for each stakeholder. ### Usability, accessibility and devices -Consider replaciing low-contrast text for the benefit of visually impaired users. - +Consider replaciing low-contrast text for the benefit of visually impaired +users. ### Branding and design No recommendations. - ### Case studies/social proof Consider adding user testimonials and/or case studies to the web page. Consider posting updates and news to the blog more regularly. - ### SEO, Analytics and site-local search **Account custodians** -* Areas such as analytics, Google Search Console, site-search (such as Google CSE or Algolia) must have at least one custodian assigned. +- Areas such as analytics, Google Search Console, site-search (such as Google + CSE or Algolia) must have at least one custodian assigned. ### Maintenance planning No recommendations. - ### Other Consider securing the [demo server][demo-server] using HTTPS. - - [etcd-io]: https://etcd.io @@ -528,11 +724,14 @@ Consider securing the [demo server][demo-server] using HTTPS. [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 [inclusive-naming]: https://inclusivenaming.org [install-check]: https://etcd.io/docs/v3.5/install/#installation-check -[website-min-reqs]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[website-min-reqs]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [assess-howto]: https://github.com/cncf/techdocs/blob/main/assessments/howto.md -[website-guidelines]: https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md +[website-guidelines]: + https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md [cncf-servicedesk]: https://servicedesk.cncf.io -[archiving-repo]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories +[archiving-repo]: + https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories [etcd-community]: https://etcd.io/community/ [etcd-howtocontrib]: https://github.com/etcd-io/etcd/blob/main/CONTRIBUTING.md [etcd-git-discuss]: https://github.com/etcd-io/etcd/discussions @@ -540,8 +739,10 @@ Consider securing the [demo server][demo-server] using HTTPS. [demo-server]: http://play.etcd.io [github-etcd-etcd]: https://github.com/etcd-io/etcd [etcdio-triage]: https://etcd.io/docs/v3.5/triage/ -[doc-optimalclustersize-23]: https://etcd.io/docs/v2.3/admin_guide#optimal-cluster-size -[docs-authentication]: https://etcd.io/docs/v3.5/op-guide/authentication/authentication/ +[doc-optimalclustersize-23]: + https://etcd.io/docs/v2.3/admin_guide#optimal-cluster-size +[docs-authentication]: + https://etcd.io/docs/v3.5/op-guide/authentication/authentication/ [etcd-readme]: https://github.com/etcd-io/etcd/blob/main/README.md [k8s-doc]: https://kubernetes.io/docs/home/ [website-repo]: https://github.com/etcd-io/website/tree/main diff --git a/analyses/0010-etcd/etcd-implementation.md b/analyses/0010-etcd/etcd-implementation.md index 320cc59..a6e254c 100644 --- a/analyses/0010-etcd/etcd-implementation.md +++ b/analyses/0010-etcd/etcd-implementation.md @@ -5,203 +5,311 @@ tags: etcd # Introduction -This document provides actionable suggestions for improving the etcd technical documentaiton. +This document provides actionable suggestions for improving the etcd technical +documentaiton. -For an analysis and general discussion of recommendations on etcd technical documentation, see [etcd-analysis.md][etcd-analysis]. +For an analysis and general discussion of recommendations on etcd technical +documentation, see [etcd-analysis.md][etcd-analysis]. ## 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. +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: - Complete and update instructional documentation: - - Describe etcd's user roles (personas). - - Document Kubernetes and Linux installation procedures. - - Update and clarify quick start and new user workflows. - - Document key tasks as procedures rather than tutorials. - - Clarify which user roles (personas) each task is for. - - Going forward, write release notes for each major and minor release. + - Describe etcd's user roles (personas). + - Document Kubernetes and Linux installation procedures. + - Update and clarify quick start and new user workflows. + - Document key tasks as procedures rather than tutorials. + - Clarify which user roles (personas) each task is for. + - Going forward, write release notes for each major and minor release. - Reorganize the documentation. - - Move *project* documentation (documentation for OSS contributors) to the etcd GitHub repo. Move *product* documentation (documentation for those who use the etcd software, in any capacity) to the technical documentation in the website repo. - - Make instructional documentation (tasks and procedures) easier to find by putting them in their own section (like the tutorials currently are). Rename the "Tutorials" section to "Tasks". The tutorials in the current doc are actually granular tasks. - - Rename the "Learning" section to something more descriptive such as "Technical Overview", and move it near the top of the table of contents. - - Consolidate all reference information (APIs and Glossary) to a reference-specific section. - - Remove information about old software revisions from the current version's docs if it's not necessary for a significant segment of users. This includes upgrade procedures and performance benchmarks. - + - Move _project_ documentation (documentation for OSS contributors) to the + etcd GitHub repo. Move _product_ documentation (documentation for those who + use the etcd software, in any capacity) to the technical documentation in + the website repo. + - Make instructional documentation (tasks and procedures) easier to find by + putting them in their own section (like the tutorials currently are). Rename + the "Tutorials" section to "Tasks". The tutorials in the current doc are + actually granular tasks. + - Rename the "Learning" section to something more descriptive such as + "Technical Overview", and move it near the top of the table of contents. + - Consolidate all reference information (APIs and Glossary) to a + reference-specific section. + - Remove information about old software revisions from the current version's + docs if it's not necessary for a significant segment of users. This includes + upgrade procedures and performance benchmarks. # Implementation: Complete and update documentation -In general, ensure that task-based documentation is complete and accurate. Write common tasks as step-by-step instructions in individual descriptions, each with the goal of walking the user through completion of the task. This is distinct from tutorials, which are designed to teach the user how to accomplish a more complex use case. +In general, ensure that task-based documentation is complete and accurate. Write +common tasks as step-by-step instructions in individual descriptions, each with +the goal of walking the user through completion of the task. This is distinct +from tutorials, which are designed to teach the user how to accomplish a more +complex use case. -Currently, the "Tutorials" section in the documentation contains tasks that should be documented as such. +Currently, the "Tutorials" section in the documentation contains tasks that +should be documented as such. -For example, the [How to access etcd][access-tutorial] tutorial should be two separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on the CLI". +For example, the [How to access etcd][access-tutorial] tutorial should be two +separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on the CLI". -Name the tasks using gerund phrases ("-ing" form, like "Reading ..." and "Writing ..."). Eliminate "How to", which clutters the heading with a redundant phrase that the user must skip over. +Name the tasks using gerund phrases ("-ing" form, like "Reading ..." and +"Writing ..."). Eliminate "How to", which clutters the heading with a redundant +phrase that the user must skip over. ## Describe etcd's user roles -In an "Overview" or "Start here" page, outline etcd's user roles or personas. These probably include: -- *Evaluator*: Someone trying to determine whether etcd is appropriate for their product, project, or organization. -- *Admin or Operator*: Someone reponsible for setting up and maintaining a standalone (not installed as the backstore for Kubernetes) production etcd service. -- *Kubernetes Admin*: Someone responsible for installing and maintaining a Kubernetes cluster that uses etcd as the backstore. -- *Developer*: Someone incorporating or integrating etcd into an application or service. +In an "Overview" or "Start here" page, outline etcd's user roles or personas. +These probably include: + +- _Evaluator_: Someone trying to determine whether etcd is appropriate for their + product, project, or organization. +- _Admin or Operator_: Someone reponsible for setting up and maintaining a + standalone (not installed as the backstore for Kubernetes) production etcd + service. +- _Kubernetes Admin_: Someone responsible for installing and maintaining a + Kubernetes cluster that uses etcd as the backstore. +- _Developer_: Someone incorporating or integrating etcd into an application or + service. ## Write installation instructions for Kubernetes -"Installation as part of Kubernetes installation" is missing. This is a task for the Kubernetes Admin role. The etcd install page can link to Kubernetes documentation, especially in cases where the Kubernetes installation process automatically includes the etcd install. The etcd documentation should include etcd-specific instructions that aren't included in the Kubernetes doc. If in doubt, duplicating instructions between the two products is preferable to omitting documentation. +"Installation as part of Kubernetes installation" is missing. This is a task for +the Kubernetes Admin role. The etcd install page can link to Kubernetes +documentation, especially in cases where the Kubernetes installation process +automatically includes the etcd install. The etcd documentation should include +etcd-specific instructions that aren't included in the Kubernetes doc. If in +doubt, duplicating instructions between the two products is preferable to +omitting documentation. ## Write Linux installation instructions -Linux installation instructions are missing ("TDB") from the Installation page. Write and test a procedure for this. +Linux installation instructions are missing ("TDB") from the Installation page. +Write and test a procedure for this. ## Update quickstart and new user workflows -Write separate "Getting started" workflows for Developer, Standalone Operator, and Kubernetes Admin users. Again, the Kubernetes Admin documentation can link to coverage in the Kubernetes documentation, but the writer should ensure that major use cases are covered, including adding details in the etcd documentation if necessary. - +Write separate "Getting started" workflows for Developer, Standalone Operator, +and Kubernetes Admin users. Again, the Kubernetes Admin documentation can link +to coverage in the Kubernetes documentation, but the writer should ensure that +major use cases are covered, including adding details in the etcd documentation +if necessary. # Reorganize the documentation ## General reorganization Reorganized the documentation to contain the following main elements: + - Architectural and system overview (Much of the current "Learning" section) - "Start here" overview: - - Explanation of user roles and use cases - - Quick start for each user role - - Detailed installation and configuration for each user role (Contents of current "Installation" page) + - Explanation of user roles and use cases + - Quick start for each user role + - Detailed installation and configuration for each user role (Contents of + current "Installation" page) - Developer guide - Operator guide - Standalone etcd installation - Kubernetes Admin - Troubleshooting - Reference - - Configuration - - CLIs - - APIs - - Logs and error messages - - Glossary + - Configuration + - CLIs + - APIs + - Logs and error messages + - Glossary - Release notes -Following are specific recommendations for each section of the documentation. +Following are specific recommendations for each section of the documentation. + +**Quickstart**: Rename to "Quick start" (two words). Add a "Prerequisites" +section and revise the "What's next" section to focus on three separate paths: -**Quickstart**: Rename to "Quick start" (two words). Add a "Prerequisites" section and revise the "What's next" section to focus on three separate paths: - Development - Operations - Kubernetes backstore -For the developer path, link to the "Set up a local cluster" page rather than the install page. +For the developer path, link to the "Set up a local cluster" page rather than +the install page. -**Demo**: Redundant with Operations guide > Authentication guides > Authentication. Remove from the ToC. +**Demo**: Redundant with Operations guide > Authentication guides > +Authentication. Remove from the ToC. -**Tutorials**: Rename "Tasks". Rename each task by removing "How to" and using "-ing" verb form. Make steps in each task explicit; one-step tasks are okay. Organize by user role: Developer, Operator, or Kubernetes Admin, or put each roles' tasks in the corresponding guide. +**Tutorials**: Rename "Tasks". Rename each task by removing "How to" and using +"-ing" verb form. Make steps in each task explicit; one-step tasks are okay. +Organize by user role: Developer, Operator, or Kubernetes Admin, or put each +roles' tasks in the corresponding guide. -**Install**: Rename "Installation" and put each installation on a separate page, collapsible in the ToC. Each should contain Prerequisites, step-by-step instructions, and a "What's next?" section. +**Install**: Rename "Installation" and put each installation on a separate page, +collapsible in the ToC. Each should contain Prerequisites, step-by-step +instructions, and a "What's next?" section. -**FAQ**: Move to near the end of the ToC. Longer explanations in the FAQ might be better as part of conceptual information -- for example, in the system or architecture overview. +**FAQ**: Move to near the end of the ToC. Longer explanations in the FAQ might +be better as part of conceptual information -- for example, in the system or +architecture overview. -**Libraries and tools**: Move to the Reference section. Consider organizing by user role, or labeling each tool or library by user role. Move "Projects using etcd" to a logo wall or at least to its own page on the website. +**Libraries and tools**: Move to the Reference section. Consider organizing by +user role, or labeling each tool or library by user role. Move "Projects using +etcd" to a logo wall or at least to its own page on the website. **Metrics**: Move to the Operations Guide. -**Reporting bugs**: Combine with the "Triage" topics and move to the repo. Include references to this contributor information in the Developer and Operations guides. +**Reporting bugs**: Combine with the "Triage" topics and move to the repo. +Include references to this contributor information in the Developer and +Operations guides. **Tuning**: Move to the Operations Guide. -**Discovery service protocol**: This page is duplicated in the Developer Guide; see the note there. Remove it from here. +**Discovery service protocol**: This page is duplicated in the Developer Guide; +see the note there. Remove it from here. **Logging conventions**: Move to the Operations Guide or the Reference section. -**Golang modules**: Remove from the ToC. Include this information in the architecture overview. +**Golang modules**: Remove from the ToC. Include this information in the +architecture overview. -**Learning**: Rename/revamp as "System Overview" or "Architecture Overview" explaining the conceptual underpinnings of etcd. Move to earlier in ToC, perhaps before "Installation". Recommendations for existing subsections follow. +**Learning**: Rename/revamp as "System Overview" or "Architecture Overview" +explaining the conceptual underpinnings of etcd. Move to earlier in ToC, perhaps +before "Installation". Recommendations for existing subsections follow. -***Data model***: Include in architecture overview. +**_Data model_**: Include in architecture overview. -***etcd client design***: Include in architecture overview. +**_etcd client design_**: Include in architecture overview. -***etcd learner design***: Include in architecture overview. +**_etcd learner design_**: Include in architecture overview. -***etcd v3 authentication design***: Include in architecture overview. +**_etcd v3 authentication design_**: Include in architecture overview. -***etcd API***: Include in architecture overview. +**_etcd API_**: Include in architecture overview. -***KV API guarantees***: Include in architecture overview. +**_KV API guarantees_**: Include in architecture overview. -***etcd versus other key-value stores***: I think this properly belongs on the webpage as an evaluation tool. Also, it needs to be updated. +**_etcd versus other key-value stores_**: I think this properly belongs on the +webpage as an evaluation tool. Also, it needs to be updated. -***Glossary***: Move to Reference section. +**_Glossary_**: Move to Reference section. -**Developer guide**: This should contain instructional content (tasks, procedures, tutorials) for developers looking to use etcd in an application. Since there are such a large number of APIs and supported interfaces, consider organizing this information by language, at least partially. In general, consider rewriting sections in this guide to be step-by-step tasks. +**Developer guide**: This should contain instructional content (tasks, +procedures, tutorials) for developers looking to use etcd in an application. +Since there are such a large number of APIs and supported interfaces, consider +organizing this information by language, at least partially. In general, +consider rewriting sections in this guide to be step-by-step tasks. -***Discovery service protocol***: What is the use case for this information? If it's to enable a developer to programmatically discover a cluster, leave it here. It might also belong in the Operations guide (but link to the same page, don't copy it), perhaps in the Clustering Guide. +**_Discovery service protocol_**: What is the use case for this information? If +it's to enable a developer to programmatically discover a cluster, leave it +here. It might also belong in the Operations guide (but link to the same page, +don't copy it), perhaps in the Clustering Guide. -***Set up a local cluster***: Make this the first section in the Developer guide. Link from the Developer Quick start rather than sending a developer to the Install page. +**_Set up a local cluster_**: Make this the first section in the Developer +guide. Link from the Developer Quick start rather than sending a developer to +the Install page. -***Interacting with etcd***: This page is largely redundant with the Tutorials. Make each task its own page, and consolidate with Tasks as described in "Tutorials" above. +**_Interacting with etcd_**: This page is largely redundant with the Tutorials. +Make each task its own page, and consolidate with Tasks as described in +"Tutorials" above. -***Why gRPC gateway***: Put the introductory material (that describes why you'd want to use gRPC) in the system overview. Present the rest of as its own sub-guide in the Tasks section or as a guide in the Developer Guide. A complete reference to the options should be available in the Reference section. +**_Why gRPC gateway_**: Put the introductory material (that describes why you'd +want to use gRPC) in the system overview. Present the rest of as its own +sub-guide in the Tasks section or as a guide in the Developer Guide. A complete +reference to the options should be available in the Reference section. -***gRPC naming and discovery***: Combine with the gRPC gateway sub-guide (See Why gRPC gateway). +**_gRPC naming and discovery_**: Combine with the gRPC gateway sub-guide (See +Why gRPC gateway). -***etcd features***: Rename "Feature lifecycle" or "Feature maturity". This information might belong in the system overview, but it seems relevant to developers and admins alike. Also, reference this article from the release notes. +**_etcd features_**: Rename "Feature lifecycle" or "Feature maturity". This +information might belong in the system overview, but it seems relevant to +developers and admins alike. Also, reference this article from the release +notes. -***API reference***: Move to Reference section. +**_API reference_**: Move to Reference section. -***API reference: concurrency***: Move to Reference section. +**_API reference: concurrency_**: Move to Reference section. -**Operations guide**: Split into guides for two distinct user roles: Operators of standalone etcd installations, and Kubernetes admins using etcd as the Kubernetes backing store. The Kubernetes Admin guide can link to the Kubernetes technical documentation and the standalone Operations guide where necessary; this is usually preferable to duplicating information. The Kubernetes and etcd projects should communicate about how best to document etcd operation in Kubernetes; as far as I can tell this has not been done. In general, consider rewriting sections in this guide to be step-by-step tasks; in many cases it's not immediately clear what to do, even if CLI examples are given. +**Operations guide**: Split into guides for two distinct user roles: Operators +of standalone etcd installations, and Kubernetes admins using etcd as the +Kubernetes backing store. The Kubernetes Admin guide can link to the Kubernetes +technical documentation and the standalone Operations guide where necessary; +this is usually preferable to duplicating information. The Kubernetes and etcd +projects should communicate about how best to document etcd operation in +Kubernetes; as far as I can tell this has not been done. In general, consider +rewriting sections in this guide to be step-by-step tasks; in many cases it's +not immediately clear what to do, even if CLI examples are given. -***Authentication Guides*** +**_Authentication Guides_** -***Authentication***: Incomplete. +**_Authentication_**: Incomplete. -***Configuration options***: Move to Reference section. +**_Configuration options_**: Move to Reference section. -***Transport security model***: Rename to "Setting up transport layer security". +**_Transport security model_**: Rename to "Setting up transport layer security". -***Clustering Guide***: Consider breaking up into one page per procedure. +**_Clustering Guide_**: Consider breaking up into one page per procedure. -***Run etcd clusters inside containers***: Put in the Clustering Guide. +**_Run etcd clusters inside containers_**: Put in the Clustering Guide. -***Failure modes***: Conceptual information. Consider moving to the architecture overview. What to actually do in case of a failure should be in a Troubleshooting section, like for example the following "Disaster recovery" section. +**_Failure modes_**: Conceptual information. Consider moving to the architecture +overview. What to actually do in case of a failure should be in a +Troubleshooting section, like for example the following "Disaster recovery" +section. -***Disaster recovery***: Consolidate with other troubleshooting procedures. +**_Disaster recovery_**: Consolidate with other troubleshooting procedures. -***Hardware recommendations***: System prerequisite. Move to somewhere before the Cluster Installation section; maybe even put it in a Prereq heading in that section. +**_Hardware recommendations_**: System prerequisite. Move to somewhere before +the Cluster Installation section; maybe even put it in a Prereq heading in that +section. -***Maintenance***: Maybe provide a more specific title like "Storage maintenance". +**_Maintenance_**: Maybe provide a more specific title like "Storage +maintenance". -***Design of runtime reconfiguration***: Move to architecture overview. +**_Design of runtime reconfiguration_**: Move to architecture overview. -***Supported platforms***: Combine with Hardware recommendations in a System Prerequisites section. +**_Supported platforms_**: Combine with Hardware recommendations in a System +Prerequisites section. -***Versioning***: Rename to "Versioning policy". Add a documentation versioning policy. Move to top of version list. Put a link to this version policy in every release notes. +**_Versioning_**: Rename to "Versioning policy". Add a documentation versioning +policy. Move to top of version list. Put a link to this version policy in every +release notes. -***Data Corruption***: Move to Troubleshooting section. +**_Data Corruption_**: Move to Troubleshooting section. -**Benchmarks**: Mostly redundant with Benchmark section in Operations guide > Performance. Move any non-redundant info to the Performance section in the Operations guide. Remove benchmarks of unsupported versions. +**Benchmarks**: Mostly redundant with Benchmark section in Operations guide > +Performance. Move any non-redundant info to the Performance section in the +Operations guide. Remove benchmarks of unsupported versions. -**Upgrading**: Move to the Operations guide. Remove old upgrade paths if they're no longer needed or relevant. +**Upgrading**: Move to the Operations guide. Remove old upgrade paths if they're +no longer needed or relevant. -***Upgrading etcd clusters and applications***: As far as I can tell, this page just lists the upgrade pages and isn't needed. - -**Triage**: Suggest putting this information for users and contributors in the repo and providing a link from the documentation to create a cleaner separation of product documentation and project documentation. Put the link in the intro to the Troubleshooting section. +**_Upgrading etcd clusters and applications_**: As far as I can tell, this page +just lists the upgrade pages and isn't needed. +**Triage**: Suggest putting this information for users and contributors in the +repo and providing a link from the documentation to create a cleaner separation +of product documentation and project documentation. Put the link in the intro to +the Troubleshooting section. ## Move release notes -Consider moving release notes to the documentation (from the code repo) on the basis that they are user, rather than contributor, documentation. +Consider moving release notes to the documentation (from the code repo) on the +basis that they are user, rather than contributor, documentation. Release notes should include: + - New and changed features - Known issues - Updated roadmap information - Upgrade procedures - - [etcd-analysis]: ./etcd-analysis.md diff --git a/analyses/0010-etcd/etcd-issues.md b/analyses/0010-etcd/etcd-issues.md index 128383e..e1c6137 100644 --- a/analyses/0010-etcd/etcd-issues.md +++ b/analyses/0010-etcd/etcd-issues.md @@ -5,49 +5,78 @@ tags: etcd # Overview -Here is an outline of the recommended changes to the etcd documentation. Proposed issues to be added to the project repo follow. +Here is an outline of the recommended changes to the etcd documentation. +Proposed issues to be added to the project repo follow. - Complete and update instructional documentation. - - Describe etcd's user roles (personas). Split the Operator persona into two: For standalone etcd installations, and for Kubernetes backstore installations. - - Convert tutorials to tasks. The "tutorials" as presented in the current doc are actually granular tasks. Document key tasks as procedures rather than tutorials. - - Document or link to Kubernetes backstore installation procedures. + - Describe etcd's user roles (personas). Split the Operator persona into two: + For standalone etcd installations, and for Kubernetes backstore + installations. + - Convert tutorials to tasks. The "tutorials" as presented in the current doc + are actually granular tasks. Document key tasks as procedures rather than + tutorials. + - Document or link to Kubernetes backstore installation procedures. - Document Linux installation procedures. - Update and clarify quick start and new user workflows. - Revise the Installation guide. - Make the Developer Guide task-oriented. - Make the Operations Guide task-oriented. - Reorganize the documentation. - - Make instructional documentation (tasks and procedures) easier to find by putting them in their own section (like the tutorials currently are). - - Move *project* documentation (documentation for OSS contributors) to the etcd GitHub repo. Move *product* documentation (documentation for those who use the etcd software, in any capacity) to the technical documentation in the website repo. - - Rename the "Learning" section to something more descriptive such as "Technical Overview", and move it near the top of the table of contents. - - Consolidate all reference information (APIs and Glossary) to a reference-specific section. - - Remove information about old software revisions from the current version's docs if it's not necessary for a significant segment of users. This includes upgrade procedures and performance benchmarks. - + - Make instructional documentation (tasks and procedures) easier to find by + putting them in their own section (like the tutorials currently are). + - Move _project_ documentation (documentation for OSS contributors) to the + etcd GitHub repo. Move _product_ documentation (documentation for those who + use the etcd software, in any capacity) to the technical documentation in + the website repo. + - Rename the "Learning" section to something more descriptive such as + "Technical Overview", and move it near the top of the table of contents. + - Consolidate all reference information (APIs and Glossary) to a + reference-specific section. + - Remove information about old software revisions from the current version's + docs if it's not necessary for a significant segment of users. This includes + upgrade procedures and performance benchmarks. # Complete and update instructional documentation ## Issue: Describe etcd's user roles -In an "Overview" or "Start here" page, outline etcd's user roles or personas, including: -- *Evaluator*: Someone trying to determine whether etcd is appropriate for their product, project, or organization. -- *Admin or Operator*: Someonereponsible for setting up and maintaining a standalone (non-Kubernetes-backstore) production etcd service. -- *Kubernetes Admin*: Someone responsible for a Kubernetes cluster using etcd as a backstore. -- *Developer*: Someone incorporating or integrating etcd into an application or service. +In an "Overview" or "Start here" page, outline etcd's user roles or personas, +including: -In each user role section, provide a link to the beginning of a "getting started" workflow, either a Quick-start or Installation instructions. +- _Evaluator_: Someone trying to determine whether etcd is appropriate for their + product, project, or organization. +- _Admin or Operator_: Someonereponsible for setting up and maintaining a + standalone (non-Kubernetes-backstore) production etcd service. +- _Kubernetes Admin_: Someone responsible for a Kubernetes cluster using etcd as + a backstore. +- _Developer_: Someone incorporating or integrating etcd into an application or + service. -## Issue: Convert Tutorials to Tasks +In each user role section, provide a link to the beginning of a "getting +started" workflow, either a Quick-start or Installation instructions. -Rename the "Tutorials" section "Tasks". Split this Task section by user role and put the resulting two sections in their respective user guides: Developer and Operations. +## Issue: Convert Tutorials to Tasks -Rename each task by removing "How to" and using the "-ing" verb form. Make steps in each task explicit; one-step tasks are okay. +Rename the "Tutorials" section "Tasks". Split this Task section by user role and +put the resulting two sections in their respective user guides: Developer and +Operations. -Rewrite each Tutorial as step-by-step instructions for a single task in an individual description. The goal is to walk the user through the completion of the task. For example, the [How to access etcd][access-tutorial] tutorial should be two separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on the CLI". +Rename each task by removing "How to" and using the "-ing" verb form. Make steps +in each task explicit; one-step tasks are okay. +Rewrite each Tutorial as step-by-step instructions for a single task in an +individual description. The goal is to walk the user through the completion of +the task. For example, the [How to access etcd][access-tutorial] tutorial should +be two separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on +the CLI". ## Issue: Write installation instructions for Kubernetes -Write the procedure [Installation as part of Kubernetes installation](install/#installation-as-part-of-kubernetes-installation), or link to Kubernetes documentation that includes etcd installation as backstore. Explain and fill in (on the etcd docs page) any gaps in the procedure. +Write the procedure +[Installation as part of Kubernetes installation](install/#installation-as-part-of-kubernetes-installation), +or link to Kubernetes documentation that includes etcd installation as +backstore. Explain and fill in (on the etcd docs page) any gaps in the +procedure. ## Issue: Write Linux installation instructions @@ -55,49 +84,83 @@ Write [installation instructions for Linux](install/#linux). ## Issue: Update quickstart and new user workflows -Rename to "Quick start" (two words). Add a "Prerequisites" section and revise the "What's next" section to focus on two separate paths, Development and Operations. Write separate "Getting started" workflows for Developer and Operator users. For the developer path, link to the "Set up a local cluster" page rather than the install page. +Rename to "Quick start" (two words). Add a "Prerequisites" section and revise +the "What's next" section to focus on two separate paths, Development and +Operations. Write separate "Getting started" workflows for Developer and +Operator users. For the developer path, link to the "Set up a local cluster" +page rather than the install page. ## Issue: Revise the installation guide -In the introduction to the installation instructions, briefly describe why a user should prefer using one installation procedure over another. Distinguish between production installations and local clusters for development or demo purposes. Include a link to the page for setting up a local cluster. - -Consider separating the install procedures and putting each on its own separate page. +In the introduction to the installation instructions, briefly describe why a +user should prefer using one installation procedure over another. Distinguish +between production installations and local clusters for development or demo +purposes. Include a link to the page for setting up a local cluster. +Consider separating the install procedures and putting each on its own separate +page. ## Issue: Make the Developer Guide task-oriented -The Developer Guide should contain instructional content (tasks, procedures, tutorials) for developers looking to use etcd in an application. In general, rewrite instructional sections in this guide to be step-by-step tasks. Move reference material into an omnibus reference section or into a reference section at the end of the Developer Guide. +The Developer Guide should contain instructional content (tasks, procedures, +tutorials) for developers looking to use etcd in an application. In general, +rewrite instructional sections in this guide to be step-by-step tasks. Move +reference material into an omnibus reference section or into a reference section +at the end of the Developer Guide. -Since there are such a large number of APIs and supported interfaces, consider organizing this information by language or providing an index page to language-specific task and reference pages. +Since there are such a large number of APIs and supported interfaces, consider +organizing this information by language or providing an index page to +language-specific task and reference pages. Following are comments on the existing sections within the Developer Guide. ### Discovery service protocol -What is the use case for this information? If it's to enable a developer to programmatically discover a cluster, leave it here. It might also belong in the Operations guide, perhaps in the Clustering Guide (but link to the same page, don't duplicate it). +What is the use case for this information? If it's to enable a developer to +programmatically discover a cluster, leave it here. It might also belong in the +Operations guide, perhaps in the Clustering Guide (but link to the same page, +don't duplicate it). ### Set up a local cluster -Make this the first section in the Developer guide. Link from the Developer Quick start -- this is the server install that a developer should see first, not the (Production) Install page. +Make this the first section in the Developer guide. Link from the Developer +Quick start -- this is the server install that a developer should see first, not +the (Production) Install page. ### Why gRPC gateway -This section is mostly about how to use the gRPC gateway. Put the introductory material (that describes why you'd want to use gRPC) in the system overview. Present the rest as a task or tasks in the Tasks section of the Developer Guide. A complete reference to the options should be available in the Reference section. +This section is mostly about how to use the gRPC gateway. Put the introductory +material (that describes why you'd want to use gRPC) in the system overview. +Present the rest as a task or tasks in the Tasks section of the Developer Guide. +A complete reference to the options should be available in the Reference +section. ### gRPC naming and discovery -Include the tasks from this section in the gRPC section of the Developer tasks. Include explanatory material in the system overview with the gRPC explanation. +Include the tasks from this section in the gRPC section of the Developer tasks. +Include explanatory material in the system overview with the gRPC explanation. ### etcd features -This information is a duplicate of the [Features](https://github.com/etcd-io/etcd/blob/main/Documentation/contributor-guide/features.md) maturity information in the repo. Remove from the Developer guide, but reference the repo Features article from the release notes. - +This information is a duplicate of the +[Features](https://github.com/etcd-io/etcd/blob/main/Documentation/contributor-guide/features.md) +maturity information in the repo. Remove from the Developer guide, but reference +the repo Features article from the release notes. ## Issue: Make the Operations guide task-oriented -The Operations Guide should contain instructional content (tasks, procedures, tutorials) for admins looking set up a production etcd service. In general, rewrite instructional sections in this guide to be step-by-step tasks. Move reference material into an omnibus reference section or into a reference section at the end of the Operations Guide. +The Operations Guide should contain instructional content (tasks, procedures, +tutorials) for admins looking set up a production etcd service. In general, +rewrite instructional sections in this guide to be step-by-step tasks. Move +reference material into an omnibus reference section or into a reference section +at the end of the Operations Guide. -Split the Operations guide into two parts for two distinct user roles: one for Operators of standalone installations of etcd, one for Kubernetes Admins using etcd as a backing store. Link from/to page rather than duplicating information common to both. Similarly, link from/to the Kubernetes project documentation in the etcd Kubernetes Admin docs to avoid duplicating documentation if practical; however, duplication is preferable to leaving something undocumented. +Split the Operations guide into two parts for two distinct user roles: one for +Operators of standalone installations of etcd, one for Kubernetes Admins using +etcd as a backing store. Link from/to page rather than duplicating information +common to both. Similarly, link from/to the Kubernetes project documentation in +the etcd Kubernetes Admin docs to avoid duplicating documentation if practical; +however, duplication is preferable to leaving something undocumented. Following are comments on the existing sections within the Operations Guide. @@ -119,7 +182,9 @@ Consider breaking up into one page per procedure. ### Failure modes -This is conceptual information. Consider moving to the system overview. What to actually do in case of a failure, for example the following "Disaster recovery" section, should be in the Troubleshooting section. +This is conceptual information. Consider moving to the system overview. What to +actually do in case of a failure, for example the following "Disaster recovery" +section, should be in the Troubleshooting section. ### Disaster recovery @@ -127,30 +192,39 @@ Move to the Troubleshooting section. ### Hardware recommendations -This is a system prerequisite. Create a Prerequisites page in the Cluster Installation section. +This is a system prerequisite. Create a Prerequisites page in the Cluster +Installation section. ### Maintenance -Consider providing a more specific, task-oriented title like "Maintaining a cluster". +Consider providing a more specific, task-oriented title like "Maintaining a +cluster". ### Design of runtime reconfiguration -Move conceptual information from this page to the architecture overview. Replace this page with a procedure ("Reconfiguring a running cluster"). +Move conceptual information from this page to the architecture overview. Replace +this page with a procedure ("Reconfiguring a running cluster"). ### Supported platforms -Combine with [Hardware recommendations](#hardware-recommendations) in a System Prerequisites section. +Combine with [Hardware recommendations](#hardware-recommendations) in a System +Prerequisites section. ### Versioning -Rename to "Versioning policy". Move to the top of the version list. Put a link to this version policy in every Release notes. - -Add a documentation versioning policy that describes when a new version of the documentation is written (major releases?); when documentation is updated instead (minor releases?); when release notes are written (major and minor releases but not patches?); and when documentation is archived. +Rename to "Versioning policy". Move to the top of the version list. Put a link +to this version policy in every Release notes. +Add a documentation versioning policy that describes when a new version of the +documentation is written (major releases?); when documentation is updated +instead (minor releases?); when release notes are written (major and minor +releases but not patches?); and when documentation is archived. # Reorganize the documentation -Move reference and conceptual topics out of the task-based documentation and into their own (new, if necessary) sections. Write documentation as needed to fill gaps in the conceptual or reference sections. +Move reference and conceptual topics out of the task-based documentation and +into their own (new, if necessary) sections. Write documentation as needed to +fill gaps in the conceptual or reference sections. ## Issue: Reorganize the documentation @@ -160,7 +234,8 @@ Reorganize the documentation to follow this suggested outline: - "Start here" overview: - Explanation of user roles and use cases - Quick start for each user role - - Detailed installation and configuration for each user role (Contents of current "Installation" page plus Local cluster install) + - Detailed installation and configuration for each user role (Contents of + current "Installation" page plus Local cluster install) - Developer guide - Operator guide - Troubleshooting @@ -172,85 +247,102 @@ Reorganize the documentation to follow this suggested outline: - Glossary - Release notes -The goal is to organize the site around the task documentation so that users can find instructions for what they need to do quickly and navigate there directly. Conceptual and reference information should be separate, and linked where necessary to support this goal. +The goal is to organize the site around the task documentation so that users can +find instructions for what they need to do quickly and navigate there directly. +Conceptual and reference information should be separate, and linked where +necessary to support this goal. -The following tables contain suggested ToC additions, page deletions, and page moves. Conceptual and task documentation requiring writing or rewriting are described in separate Issues. +The following tables contain suggested ToC additions, page deletions, and page +moves. Conceptual and task documentation requiring writing or rewriting are +described in separate Issues. ### Add sections Sections to be added to the table of contents. -| Section | Description | -| -- | -- | -| Reference | A library of reference documents: APIs, CLIs, configuration options, and anything else a user might need to look up to complete a task. | -| Troubleshooting | A list of procedures for diagnosing and fixing problems. | -| Release Notes | The cumulative release notes for the major and minor release. See [Release Notes](#add-release-notes-to-new-releases). +| Section | Description | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| Reference | A library of reference documents: APIs, CLIs, configuration options, and anything else a user might need to look up to complete a task. | +| Troubleshooting | A list of procedures for diagnosing and fixing problems. | +| Release Notes | The cumulative release notes for the major and minor release. See [Release Notes](#add-release-notes-to-new-releases). | ### Remove pages -Pages to be removed entirely or cannibalized and their contents integrated elsewhere. Links (listed in the table) will need to be removed or updated as well. If the page duplicates or largely overlaps information on another page, that page is listed as "Redundant with". Page URLs are relative to `https://etcd.io/docs/v3.5/`. - -| Page | Links | Redundant with | Suggested action | -| -- | -- | -- | -- | -| demo/ | | op-guide/authentication/authentication/ | Remove | -| dev-internal/discovery_protocol/ | op-guide/clustering/ | dev-guide/discovery_protocol/ | Remove | -| /dev-guide/interacting_v3/ | dev-guide/local_cluster/ | tutorials/*.md | Consolidate under "Tasks". See [Tutorials](#tutorials) | -| op-guide/recovery/ | op-guide/failures/, op-guide/runtime-configuration/, op-guide/runtime-reconf-design/ | | Incorporate into Troubleshooting guide | -| op-guide/data_corruption/ | op-guide/monitoring/ | | Incorporate into Troubleshooting guide | -| upgrades/ | | | Remove or archive old upgrade paths if they're no longer needed or supported. | -| dev-guide/features/ | | | Remove from the Developer guide. See [etcd features](#etcd-features). | +Pages to be removed entirely or cannibalized and their contents integrated +elsewhere. Links (listed in the table) will need to be removed or updated as +well. If the page duplicates or largely overlaps information on another page, +that page is listed as "Redundant with". Page URLs are relative to +`https://etcd.io/docs/v3.5/`. + +| Page | Links | Redundant with | Suggested action | +| -------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------- | ----------------------------------------------------------------------------- | +| demo/ | | op-guide/authentication/authentication/ | Remove | +| dev-internal/discovery_protocol/ | op-guide/clustering/ | dev-guide/discovery_protocol/ | Remove | +| /dev-guide/interacting_v3/ | dev-guide/local_cluster/ | tutorials/\*.md | Consolidate under "Tasks". See [Tutorials](#tutorials) | +| op-guide/recovery/ | op-guide/failures/, op-guide/runtime-configuration/, op-guide/runtime-reconf-design/ | | Incorporate into Troubleshooting guide | +| op-guide/data_corruption/ | op-guide/monitoring/ | | Incorporate into Troubleshooting guide | +| upgrades/ | | | Remove or archive old upgrade paths if they're no longer needed or supported. | +| dev-guide/features/ | | | Remove from the Developer guide. See [etcd features](#etcd-features). | ### Move pages -Pages to be moved as-is, usually under an organizing heading. Links (listed in the table) will need to be updated. Page URLs are relative to `https://etcd.io/docs/v3.5/`. - -| Page | Links | Suggested action | -| -- | -- | -- | -| metrics/ | | Move to the Operations Guide. | -| learning/glossary/ | | Move to Reference section. | -| tuning/ | op-guide/hardware/, quickstart/ | Move to the Operations Guide. | -| dev-internal/logging/ | | Move to the Reference section. Link from the Operations guide. | -| dev-internal/modules/ | | Move to Architecture overview. | -| integrations/ | quickstart/ | Move to the Reference section. Consider organizing by user role , or labeling each tool or library by user role. | -| integrations/#projects-using-etcd | quickstart/ | Move to a logo wall or at least to its own page on the website. | -| reporting_bugs/ | | Combine with the "Triage" topics and move to the repo's Contributor guide. Link from the Troubleshooting guide. | -| faq/ | | Move to near the end of the ToC. | -| dev-guide/api_reference_v3/ | op-guide/runtime-configuration/ | Move to the Reference section. | -| dev-guide/api_concurrency_reference_v3/ | | Move to the Reference section. | -| op-guide/container/ | | Put in the Clustering Guide. | -| op-guide/configuration/ | quickstart/ | Put in the Reference section. | -| upgrades/ | | Move to the Operations guide. | -| triage/ | | Move to the repo and provide a link from the documentation (release notes) to create a cleaner separation of product documentation and project documentation. | - +Pages to be moved as-is, usually under an organizing heading. Links (listed in +the table) will need to be updated. Page URLs are relative to +`https://etcd.io/docs/v3.5/`. + +| Page | Links | Suggested action | +| --------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| metrics/ | | Move to the Operations Guide. | +| learning/glossary/ | | Move to Reference section. | +| tuning/ | op-guide/hardware/, quickstart/ | Move to the Operations Guide. | +| dev-internal/logging/ | | Move to the Reference section. Link from the Operations guide. | +| dev-internal/modules/ | | Move to Architecture overview. | +| integrations/ | quickstart/ | Move to the Reference section. Consider organizing by user role , or labeling each tool or library by user role. | +| integrations/#projects-using-etcd | quickstart/ | Move to a logo wall or at least to its own page on the website. | +| reporting_bugs/ | | Combine with the "Triage" topics and move to the repo's Contributor guide. Link from the Troubleshooting guide. | +| faq/ | | Move to near the end of the ToC. | +| dev-guide/api_reference_v3/ | op-guide/runtime-configuration/ | Move to the Reference section. | +| dev-guide/api_concurrency_reference_v3/ | | Move to the Reference section. | +| op-guide/container/ | | Put in the Clustering Guide. | +| op-guide/configuration/ | quickstart/ | Put in the Reference section. | +| upgrades/ | | Move to the Operations guide. | +| triage/ | | Move to the repo and provide a link from the documentation (release notes) to create a cleaner separation of product documentation and project documentation. | ## Issue: Move release notes to user documentation -Move the release notes out of the repo and into to the user documentation. +Move the release notes out of the repo and into to the user documentation. Release notes should include: + - New and changed features - Known issues - Updated roadmap information - Upgrade procedures - All release-specific information - ## Issue: Consolidate all reference information -Consolidate all reference information (APIs and Glossary) to a reference-specific section. +Consolidate all reference information (APIs and Glossary) to a +reference-specific section. -Or, create user role-specific reference sections within the Developer and Operations guides. Since some of the material overlaps, a single reference section is probably easier. +Or, create user role-specific reference sections within the Developer and +Operations guides. Since some of the material overlaps, a single reference +section is probably easier. ## Issue: Revise the FAQ -Longer explanations in the FAQ might be better as part of conceptual information -- for example, in the system or architecture overview. Retain the short answers that don't fit elesewhere. - +Longer explanations in the FAQ might be better as part of conceptual information +-- for example, in the system or architecture overview. Retain the short answers +that don't fit elesewhere. ## Issue: Create a System Overview -Rename the "Learning" section to "System Overview" or "Conceptual Overview". This is the place for detailed explanations of the system philosophy, design, and architeture. Edit the content, limiting it to explaining concepts. Move instructional and reference topics to their own areas of the documentation. +Rename the "Learning" section to "System Overview" or "Conceptual Overview". +This is the place for detailed explanations of the system philosophy, design, +and architeture. Edit the content, limiting it to explaining concepts. Move +instructional and reference topics to their own areas of the documentation. -Move the section to earlier in ToC, perhaps before "Installation". +Move the section to earlier in ToC, perhaps before "Installation". Recommendations follow for existing subsections of "Learning". @@ -260,11 +352,14 @@ Include in architecture overview. ### etcd client design -Include in architecture overview. Remove the Glossary and merge it into the sitewide Glossary. +Include in architecture overview. Remove the Glossary and merge it into the +sitewide Glossary. ### etcd learner design -Include in architecture overview. Eliminate references to previous and future releases; describe the current release only. Put comparisons to other releases in the release notes, if relevant. +Include in architecture overview. Eliminate references to previous and future +releases; describe the current release only. Put comparisons to other releases +in the release notes, if relevant. ### etcd v3 authentication design @@ -280,19 +375,23 @@ Include in architecture overview. Rename to "Key-value API guarantees". ### etcd versus other key-value stores -I think this properly belongs on the webpage as an evaluation tool, but if there's a case for comparing etcd to other KV stores as an instructional strategy, leave it in the system overview. In either case, it needs to be updated. - +I think this properly belongs on the webpage as an evaluation tool, but if +there's a case for comparing etcd to other KV stores as an instructional +strategy, leave it in the system overview. In either case, it needs to be +updated. ## Issue: Relocate Benchmarks -Mostly redundant with Benchmark section in Operations guide > Performance. Move any non-redundant info to Performance section in Operations guide. +Mostly redundant with Benchmark section in Operations guide > Performance. Move +any non-redundant info to Performance section in Operations guide. -Remove old benchmarks if they're no longer needed. +Remove old benchmarks if they're no longer needed. ## Issue: Remove "Upgrading > Upgrading etcd clusters and applications" -If the intent of this page is to explain upgrade paths that span more than one release, make that clear in an introduction and write an explicit procedure for each path. If such a guide isn't needed, then remove this page. - +If the intent of this page is to explain upgrade paths that span more than one +release, make that clear in an introduction and write an explicit procedure for +each path. If such a guide isn't needed, then remove this page. diff --git a/analyses/0011-keda/README.md b/analyses/0011-keda/README.md index 7249fe5..1409d20 100644 --- a/analyses/0011-keda/README.md +++ b/analyses/0011-keda/README.md @@ -3,6 +3,10 @@ title: KEDA TechDocs Analysis tags: KEDA --- -- [KEDA Doc Analysis](keda-analysis.md) - Analyzes the existing KEDA documentation and provides recommendations. -- [KEDA Implementation](keda-implementation.md) - Provides detailed and actionable recommendations, intended to be worked on as GitHub issues. -- [KEDA Issues](keda-issues.md) - A list of documentation improvements derived from KEDA Implementation, entered as issues in the [kedacore/keda-docs repo](https://github.com/kedacore/keda-docs/issues/1361). +- [KEDA Doc Analysis](keda-analysis.md) - Analyzes the existing KEDA + documentation and provides recommendations. +- [KEDA Implementation](keda-implementation.md) - Provides detailed and + actionable recommendations, intended to be worked on as GitHub issues. +- [KEDA Issues](keda-issues.md) - A list of documentation improvements derived + from KEDA Implementation, entered as issues in the + [kedacore/keda-docs repo](https://github.com/kedacore/keda-docs/issues/1361). diff --git a/analyses/0011-keda/keda-analysis.md b/analyses/0011-keda/keda-analysis.md index 0e616d9..2744b07 100644 --- a/analyses/0011-keda/keda-analysis.md +++ b/analyses/0011-keda/keda-analysis.md @@ -9,27 +9,44 @@ cSpell:ignore: Welsch dwelsch pastable # Introduction -This document analyzes the effectiveness and completeness of the [KEDA](https://keda.sh) 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 +[KEDA](https://keda.sh) 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. +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 was written to analyze the current state of KEDA documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. The companion document, keda-implementation.md, outlines an actionable plan for improvement. +This document was written to analyze the current state of KEDA documentation. It +aims to provide project leaders with an informed understanding of potential +problems in current project documentation. The companion document, +keda-implementation.md, outlines an actionable plan for improvement. This document: - Analyzes the current KEDA technical documentation and website - Compares existing documentation against the CNCF’s standards -- Recommends a program of key improvements with the largest return on investment. The companion document, keda-implementation.md, provides specific actionable suggestions and recommendations for overall organization and presentation of documentation +- Recommends a program of key improvements with the largest return on + investment. The companion document, keda-implementation.md, provides specific + actionable suggestions and recommendations for overall organization and + presentation of documentation ## Scope of analysis -The documentation discussed here includes the entire contents of the website (which contains the technical docs), as well as documentation for contributors and users on the KEDA GitHub repository. +The documentation discussed here includes the entire contents of the website +(which contains the technical docs), as well as documentation for contributors +and users on the KEDA GitHub repository. -The KEDA website and documentation are written in Markdown and are compiled using the Hugo static site generator with the Docsy theme and served from the Netlify platform. The site's code is stored on the KEDA GitHub repo. +The KEDA website and documentation are written in Markdown and are compiled +using the Hugo static site generator with the Docsy theme and served from the +Netlify platform. The site's code is stored on the KEDA GitHub repo. **In scope:** + - Website: https://keda.sh - Documentation: https://keda.sh/docs - Website repo: https://github.com/kedacore/keda-docs @@ -37,119 +54,189 @@ The KEDA website and documentation are written in Markdown and are compiled usin - Main project contributor info: https://github.com/kedacore/keda **Out of scope:** + - Other KEDA repos: https://github.com/kedacore/* ## How this document is organized -This document is divided into three sections that represent three major areas of concern: +This document is divided into three sections that represent three major areas of +concern: -- **Project documentation:** concerns documentation for users of the KEDA software, aimed at people who intend to use it -- **Contributor documentation:** concerns documentation for new and existing contributors to the KEDA OSS project -- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability +- **Project documentation:** concerns documentation for users of the KEDA + software, aimed at people who intend to use it +- **Contributor documentation:** concerns documentation for new and existing + contributors to the KEDA OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability -Each section begins with summary ratings based on a rubric with appropriate [criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) for the section, then proceeds to: -- **Comments**: observations about the existing documentation, with a focus on how it does or does not help KEDA users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness of the documentation. +Each section begins with summary ratings based on a rubric with appropriate +[criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) +for the section, then proceeds to: -An accompanying document, [keda-implementation.md](./keda-implementation.md), 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 should be tracked as a series of Github [issues]((./keda-issues.md). +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help KEDA users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. +An accompanying document, [keda-implementation.md](./keda-implementation.md), +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 should be tracked as a series of Github +[issues]((./keda-issues.md). ## How to use this document -Readers interested only in actionable improvements should skip this document and read [keda-implementation.md](./keda-implementation.md). +Readers interested only in actionable improvements should skip this document and +read [keda-implementation.md](./keda-implementation.md). -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: +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 documentation infrastructure](#website) -Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) specification. - +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the +[criteria](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) +specification. ### 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](https://www.rfc-editor.org/rfc/rfc2119), 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. - +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](https://www.rfc-editor.org/rfc/rfc2119), 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 -KEDA is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. - -| Criterion | Rating (1-5) | -| --- | --- | -| Information architecture | 2 - needs improvement | -| New user content | 2 - needs improvement | -| Content maintainability | 3 - meets standards | -| Content creation processes | 2 - needs improvement | -| Inclusive language | 2 - needs improvement | +KEDA is a **graduated** project of CNCF. This means that the project should have +[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) +standards for documentation. +| Criterion | Rating (1-5) | +| -------------------------- | --------------------- | +| Information architecture | 2 - needs improvement | +| New user content | 2 - needs improvement | +| Content maintainability | 3 - meets standards | +| Content creation processes | 2 - needs improvement | +| Inclusive language | 2 - needs improvement | ## Comments ### Information architecture -There is an overview containing **high-level conceptual** content that explains what KEDA is and how it works. The conceptual overview has one diagram, which could be more clear and align better with the text. +There is an overview containing **high-level conceptual** content that explains +what KEDA is and how it works. The conceptual overview has one diagram, which +could be more clear and align better with the text. -Installation tasks are documented, but KEDA has other **undocumented tasks**. The documentation provides reference information for configuring KEDA but does not provide **instructions** on the most common use cases (**"happy path"**), how to use KEDA in a Kubernetes deployment. +Installation tasks are documented, but KEDA has other **undocumented tasks**. +The documentation provides reference information for configuring KEDA but does +not provide **instructions** on the most common use cases (**"happy path"**), +how to use KEDA in a Kubernetes deployment. -Aside from task descriptions, the documentation seems **feature complete**. Since KEDA is essentially a single-purpose API for Kubernetes, KEDA's scope is small, with the caveat that the project contains a collection of plug-in scalers (64 at the time of this writing), maintained variously by the community and by outside entities. +Aside from task descriptions, the documentation seems **feature complete**. +Since KEDA is essentially a single-purpose API for Kubernetes, KEDA's scope is +small, with the caveat that the project contains a collection of plug-in scalers +(64 at the time of this writing), maintained variously by the community and by +outside entities. -Documentation is **not clearly named according to user goals**, but there is probably only one user role (persona) for KEDA – an administrator adding KEDA-based scaling to a Kubernetes deployment. +Documentation is **not clearly named according to user goals**, but there is +probably only one user role (persona) for KEDA – an administrator adding +KEDA-based scaling to a Kubernetes deployment. There are **escalation paths** available: + - The documentation contains a Troubleshooting section. - The documentation contains a FAQ. - The website has a blog, though posts are infrequent. -- The project has a Support page available from the website menu at Project > Support. The support page links to a contributor guide and a support policy page. +- The project has a Support page available from the website menu at Project > + Support. The support page links to a contributor guide and a support policy + page. - There is a KEDA Slack channel in the Kubernetes workspace. - There is a KEDA Discussions forum in the GitHub repo. KEDA does not feature an **API** per se. -The documentation **is versioned** with the software; doc versions each have their own directory in the repo. Release notes are provided in the project main repo, and linked from a ROADMAP file. They are not linked from the documentation pages. +The documentation **is versioned** with the software; doc versions each have +their own directory in the repo. Release notes are provided in the project main +repo, and linked from a ROADMAP file. They are not linked from the documentation +pages. ### New user content -There is partial **getting started** information in the documentation as [Deploying KEDA](https://keda.sh/docs/2.13/deploy/), the first topic in the table of contents. *Deploying KEDA* provides **installation instruction** for adding a KEDA runtime to a Kubernetes cluster. +There is partial **getting started** information in the documentation as +[Deploying KEDA](https://keda.sh/docs/2.13/deploy/), the first topic in the +table of contents. _Deploying KEDA_ provides **installation instruction** for +adding a KEDA runtime to a Kubernetes cluster. + +There are **getting started** pages on the main GitHub repo for the following +supported systems: -There are **getting started** pages on the main GitHub repo for the following supported systems: - RabbitMQ and Go - Azure Functions and Queues - Azure Functions and Kafka on OpenShift 4 - Azure Storage Queue with ScaledJob -These pages list installing KEDA as a prerequisite. Taken together, "Deploying KEDA" and the scenarios in the repo make a complete Getting Started workflow, but they are in two separate places and the scenarios are not findable from the website. +These pages list installing KEDA as a prerequisite. Taken together, "Deploying +KEDA" and the scenarios in the repo make a complete Getting Started workflow, +but they are in two separate places and the scenarios are not findable from the +website. -There are also numerous examples available in the [samples repo](https://github.com/kedacore/samples). +There are also numerous examples available in the +[samples repo](https://github.com/kedacore/samples). KEDA does not require documentation for multiple **operating systems**. -The [Operate](https://keda.sh/docs/2.13/operate/) topic in the TOC provides instructions for using KEDA and the scenarios in the repo provide user instructions. However, new users starting on the website might not **know where to go after installation**. A more explicit **getting started workflow** would be helpful. +The [Operate](https://keda.sh/docs/2.13/operate/) topic in the TOC provides +instructions for using KEDA and the scenarios in the repo provide user +instructions. However, new users starting on the website might not **know where +to go after installation**. A more explicit **getting started workflow** would +be helpful. -There is no obvious **new user signpost** in the documentation. The closest is *Deploying KEDA*, which again just gives installation instructions but no roadmap. +There is no obvious **new user signpost** in the documentation. The closest is +_Deploying KEDA_, which again just gives installation instructions but no +roadmap. -There is easily **copy-pastable** content for CLI input where appropriate, including in the installation instructions. +There is easily **copy-pastable** content for CLI input where appropriate, +including in the installation instructions. ### Content maintainability & site mechanics -The documentation is **Searchable** using functionality provided by the site generation engine. +The documentation is **Searchable** using functionality provided by the site +generation engine. -There do not seem to be any plans for **localization**. Docsy has **support for multiple languages** in case that changes. +There do not seem to be any plans for **localization**. Docsy has **support for +multiple languages** in case that changes. -The documentation is **versioned**. The repo contains a separate folder for each version. +The documentation is **versioned**. The repo contains a separate folder for each +version. ### Content creation processes -The procedure for **building and releasing a new version** is documented in the doc repo README file. +The procedure for **building and releasing a new version** is documented in the +doc repo README file. -The code contribution instructions contain brief **documentation creation and update** instructions. +The code contribution instructions contain brief **documentation creation and +update** instructions. -The MAINTAINERS doc in the website repo points to the MAINTAINERS doc in the main repo, which does not tell who is **responsible for documentation pull requests**. The website does not have a **clear owner or maintainer**. +The MAINTAINERS doc in the website repo points to the MAINTAINERS doc in the +main repo, which does not tell who is **responsible for documentation pull +requests**. The website does not have a **clear owner or maintainer**. ### Inclusive language -The documentation includes some examples of [**non-inclusive language**](https://inclusivenaming.org/). For example: +The documentation includes some examples of +[**non-inclusive language**](https://inclusivenaming.org/). For example: + - "easily", "simple", "simply", etc. - https://keda.sh/docs/2.13/deploy/ - https://keda.sh/docs/2.13/deploy/#uninstall-3 @@ -162,7 +249,10 @@ The documentation includes some examples of [**non-inclusive language**](https:/ ### Information architecture -Reorganize the Table of Contents. Rename "The KEDA Documentation"; the name is misleading since it implies that it contains the entire documentation set. I'd suggest the following changes: +Reorganize the Table of Contents. Rename "The KEDA Documentation"; the name is +misleading since it implies that it contains the entire documentation set. I'd +suggest the following changes: + - Rename "The KEDA Documentation" to "Getting Started". - Create a "Reference" topic at the end of the ToC. - Move the FAQ to the Reference section. @@ -170,13 +260,20 @@ Reorganize the Table of Contents. Rename "The KEDA Documentation"; the name is m - Rename "Operate" to "Operator Guide". - Move "Troubleshooting" to the end of the User Guide. -Move the scenarios from the KEDA GitHub repo to the user documentation on the website. Link to these from the end of "Deploying KEDA" to create a workflow for new users. +Move the scenarios from the KEDA GitHub repo to the user documentation on the +website. Link to these from the end of "Deploying KEDA" to create a workflow for +new users. -Write step-by-step tasks in the User Guide that explain how to run and use KEDA, or link to other documentation that does, for example the [Kubernetes documentation on HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). For example, explain how to do 0-to-1 scaling. +Write step-by-step tasks in the User Guide that explain how to run and use KEDA, +or link to other documentation that does, for example the +[Kubernetes documentation on HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/). +For example, explain how to do 0-to-1 scaling. ### New user content -Clearly label the starting point for new users. Make sure that there is an easy to follow workflow for installation, configuring and running a basic scaler, and any other tasks required to begin using KEDA. +Clearly label the starting point for new users. Make sure that there is an easy +to follow workflow for installation, configuring and running a basic scaler, and +any other tasks required to begin using KEDA. ### Content maintainability & site mechanics @@ -184,133 +281,151 @@ No recommendations ### Content creation processes -Make it easier to find the instructions for releasing a new version of the documentation and updating the documentation. +Make it easier to find the instructions for releasing a new version of the +documentation and updating the documentation. Document in the repo who the website/documentation maintainers are. ### Inclusive language -Remove non-inclusive language throughout the documentation as recommended on the [inclusive naming website](https://inclusivenaming.org/). - +Remove non-inclusive language throughout the documentation as recommended on the +[inclusive naming website](https://inclusivenaming.org/). # Contributor documentation -KEDA is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for contributor documentation. - -| Criterion | Rating (1-5) | -| --- | --- | -| Communication methods documented | 3 - meets standards | -| Beginner friendly issue backlog | 3 - meets standards | -| “New contributor” getting started content | 3 - meets standards | -| Project governance documentation | 4 - meets or exceeds standards | +KEDA is a **graduated** project of CNCF. This means that the project should have +[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) +standards for contributor documentation. +| Criterion | Rating (1-5) | +| ----------------------------------------- | ------------------------------ | +| Communication methods documented | 3 - meets standards | +| Beginner friendly issue backlog | 3 - meets standards | +| “New contributor” getting started content | 3 - meets standards | +| Project governance documentation | 4 - meets or exceeds standards | ## Comments ### Communication methods documented -The KEDA main repo points to **community** resources, including a KEDA Slack channel in the Kubernetes workspace. There is a **community page** on the website that invites readers to a **biweekly Zoom meeting**. The main website has direct links in the footer to the Slack community, the **GitHub** repo, and a Twitter feed. I could not find any mention of a **mailing list**. - +The KEDA main repo points to **community** resources, including a KEDA Slack +channel in the Kubernetes workspace. There is a **community page** on the +website that invites readers to a **biweekly Zoom meeting**. The main website +has direct links in the footer to the Slack community, the **GitHub** repo, and +a Twitter feed. I could not find any mention of a **mailing list**. ### Beginner friendly issue backlog -Doc **issues** in the repo are **well documented** and have been labeled and, presumably, **triaged**. +Doc **issues** in the repo are **well documented** and have been labeled and, +presumably, **triaged**. -There is a **good first issue** label (although this label is not currently applied to any issues). - -There are **stale issues**, but they seem for the most part to be managed. There are only ~30 open issues in the doc repo. +There is a **good first issue** label (although this label is not currently +applied to any issues). +There are **stale issues**, but they seem for the most part to be managed. There +are only ~30 open issues in the doc repo. ### New contributor getting started content The website contains a **community section**. -There is **CONTRIBUTORS** document in the website/documentation repo with instructions for **getting help** and building and contributing new documentation. - +There is **CONTRIBUTORS** document in the website/documentation repo with +instructions for **getting help** and building and contributing new +documentation. ### Project governance documentation -**Governance** is clearly documented in its own repo. Presumably this information is applicable to all of the repos in kedacore. - +**Governance** is clearly documented in its own repo. Presumably this +information is applicable to all of the repos in kedacore. ## Recommendations ### Communication methods documented -If there is a mailing list or other news distribution channel, add it to the community page. (Note: As discussed in the [PR](https://github.com/cncf/techdocs/pull/215), there does not seem to be a newsletter. This is OK since there are plenty of other active communication channels.) - +If there is a mailing list or other news distribution channel, add it to the +community page. (Note: As discussed in the +[PR](https://github.com/cncf/techdocs/pull/215), there does not seem to be a +newsletter. This is OK since there are plenty of other active communication +channels.) ### Beginner friendly issue backlog Revisit stale issues if they are not being reviewed. - ### New contributor getting started content No recommendations. - ### Project governance documentation No recommendations. - # Website -KEDA is a **graduated** project of CNCF. This means that the project should have [*very high*](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) standards for documentation. - -| Criterion | Rating (1-5) | -| --- | --- | -| Single-source for all files | 3 - meets standards | -| Meets min website req. (for maturity level) | 2 - needs improvement | -| Usability, accessibility, and design | 3 - meets standards | -| Branding and design | 4 - meets or exceeds standards | -| Case studies/social proof | 3 - meets standards | -| SEO, Analytics, and site-local search | 4 - meets or exceeds standards | -| Maintenance planning | 4 - meets or exceeds standards | -| A11y plan & implementation | 3 - meets standards | -| Mobile-first plan & impl. | 4 - meets or exceeds standards | -| HTTPS access & HTTP redirect | 4 - meets or exceeds standards | -| Google Analytics 4 for production only | 5 - exemplary | -| Indexing allowed for production server only | 5 - exemplary | -| Intra-site / local search | 5 - exemplary | -| Account custodians are documented | 2 - needs improvement | - +KEDA is a **graduated** project of CNCF. This means that the project should have +[_very high_](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md) +standards for documentation. + +| Criterion | Rating (1-5) | +| ------------------------------------------- | ------------------------------ | +| Single-source for all files | 3 - meets standards | +| Meets min website req. (for maturity level) | 2 - needs improvement | +| Usability, accessibility, and design | 3 - meets standards | +| Branding and design | 4 - meets or exceeds standards | +| Case studies/social proof | 3 - meets standards | +| SEO, Analytics, and site-local search | 4 - meets or exceeds standards | +| Maintenance planning | 4 - meets or exceeds standards | +| A11y plan & implementation | 3 - meets standards | +| Mobile-first plan & impl. | 4 - meets or exceeds standards | +| HTTPS access & HTTP redirect | 4 - meets or exceeds standards | +| Google Analytics 4 for production only | 5 - exemplary | +| Indexing allowed for production server only | 5 - exemplary | +| Intra-site / local search | 5 - exemplary | +| Account custodians are documented | 2 - needs improvement | ## Comments ### Single-source requirement -Source files for all website pages reside in a **single repo**. However, some user documentation pages (speciifically, "Getting started" topics linked from the main (kedacore/keda) repo) would better serve users if they were moved to the tech docs on the website. +Source files for all website pages reside in a **single repo**. However, some +user documentation pages (speciifically, "Getting started" topics linked from +the main (kedacore/keda) repo) would better serve users if they were moved to +the tech docs on the website. Website files are all in the website repo. - ### Minimal website requirements -Except for archived projects, requirements are cumulative through project maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. - -Listed and acknowledged below are the (cumulative) _minimal_ website requirements for projects based on their [maturity level](https://github.com/cncf/toc/tree/main/process#cncf-project-lifecycle--process): sandbox, incubating, graduated and archived. - -| Maturity | Requirement | Met? | -| --- | --- | --- | -| Sandbox | Majority of [Website guidelines](https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md) satisfied | Yes | -| Sandbox | [Docs assessment](https://github.com/cncf/techdocs/blob/main/assessments/howto.md) [cncf-servicedesk] completed. | Yes | -| Sandbox | **Project documentation** exists – somewhere. It is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website. (May still be in the project GitHub repo, for example.) | Yes | -| Incubating | All [Website guidelines](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md#website) satisfied | Yes | -| Incubating | Request docs (re-)assessment through CNCF [service desk](https://servicedesk.cncf.io/) | Yes | -| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | No | -| Incubating | **Project doc**: Hosted directly | Yes | -| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | Yes | -| Graduated | [Docs assessment](https://github.com/cncf/techdocs/blob/main/assessments/howto.md): all assessment follow-through actions are complete | No | -| Graduated | **Project doc** fully addresses needs of key stakeholders | No - new user doc needs improvement | -| Archived | The website repo is in an [archived state](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) | n/a | -| Archived | Archived status of the project is obvious to site visitors | n/a | -| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a | +Except for archived projects, requirements are cumulative through project +maturity levels so, for example, incubating projects must satisfy the +requirements for sandbox projects. + +Listed and acknowledged below are the (cumulative) _minimal_ website +requirements for projects based on their +[maturity level](https://github.com/cncf/toc/tree/main/process#cncf-project-lifecycle--process): +sandbox, incubating, graduated and archived. + +| Maturity | Requirement | Met? | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| Sandbox | Majority of [Website guidelines](https://github.com/cncf/techdocs/blob/main/docs/website-guidelines-checklist.md) satisfied | Yes | +| Sandbox | [Docs assessment](https://github.com/cncf/techdocs/blob/main/assessments/howto.md) [cncf-servicedesk] completed. | Yes | +| Sandbox | **Project documentation** exists – somewhere. It is acceptable at this maturity level to link out to documentation that hasn't yet been integrated into the website. (May still be in the project GitHub repo, for example.) | Yes | +| Incubating | All [Website guidelines](https://github.com/cncf/techdocs/blob/main/assessments/criteria.md#website) satisfied | Yes | +| Incubating | Request docs (re-)assessment through CNCF [service desk](https://servicedesk.cncf.io/) | Yes | +| Incubating | **Project doc**: stakeholders (roles) identified and doc needs documented | No | +| Incubating | **Project doc**: Hosted directly | Yes | +| Incubating | **Project doc**: Comprehensive, addressing most stakeholder needs | Yes | +| Graduated | [Docs assessment](https://github.com/cncf/techdocs/blob/main/assessments/howto.md): all assessment follow-through actions are complete | No | +| Graduated | **Project doc** fully addresses needs of key stakeholders | No - new user doc needs improvement | +| Archived | The website repo is in an [archived state](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) | n/a | +| Archived | Archived status of the project is obvious to site visitors | n/a | +| Archived | Link to successor project website and/or migration documentation (if it exists) | n/a | ### Usability, accessibility and devices -The website is **usable from mobile**. Top-nav is reachable only via the hamburger menu on mobile devices. There is no in-page TOC or other context on mobile devices. The footer is identical on all platforms. +The website is **usable from mobile**. Top-nav is reachable only via the +hamburger menu on mobile devices. There is no in-page TOC or other context on +mobile devices. The footer is identical on all platforms. **Search** is available from the hamburger menu as well. @@ -318,59 +433,73 @@ The website is **usable from mobile**. Top-nav is reachable only via the hamburg A **mobile-first design** does not make sense for this project. -**Color contrasts** are mostly adequate. Some blue-on-black graphics and text are probably hard to read for color- or contrast-impaired readers. +**Color contrasts** are mostly adequate. Some blue-on-black graphics and text +are probably hard to read for color- or contrast-impaired readers. -Website features, *Search* most importantly, are usable using a **keyboard only**. +Website features, _Search_ most importantly, are usable using a **keyboard +only**. -As with any text that contains a lot of code and special characters, **text-to-speech** is **not likely to offer listeners a good experience**. +As with any text that contains a lot of code and special characters, +**text-to-speech** is **not likely to offer listeners a good experience**. ### Branding and design -The website and documentation carry an **easily recognizable brand** for the project based on logo, color scheme, and template layout. The **brand is used consistently** on the site. The website's text is **easily readable**. - +The website and documentation carry an **easily recognizable brand** for the +project based on logo, color scheme, and template layout. The **brand is used +consistently** on the site. The website's text is **easily readable**. ### Case studies/social proof +I'm unable to find **case studies** or **user testimonials** for the project. +They're probably not as important for KEDA as they are for a more extensive +product, though. -I'm unable to find **case studies** or **user testimonials** for the project. They're probably not as important for KEDA as they are for a more extensive product, though. - -There is a **project blog**; posts are infrequent. The last one was in August 2023. +There is a **project blog**; posts are infrequent. The last one was in +August 2023. -There are **community talks** for the project on YouTube. One talk, from KubeCon 2022, is **present on the website**. - -There is a substantial **logo wall of users and participating organizations**. The KEDA project solicits users to register as "listed users." +There are **community talks** for the project on YouTube. One talk, from KubeCon +2022, is **present on the website**. +There is a substantial **logo wall of users and participating organizations**. +The KEDA project solicits users to register as "listed users." ### SEO, Analytics and site-local search **Analytics:** -* Analytics is enabled for the production server. -* Analytics is disabled for all other deployments. -* The website runs on the new Google Analytics (GA) 4. -* 404 reports are collected and tracked using GA4. + +- Analytics is enabled for the production server. +- Analytics is disabled for all other deployments. +- The website runs on the new Google Analytics (GA) 4. +- 404 reports are collected and tracked using GA4. **Indexing and Search:** -* The production site is well indexed. -* Local intra-site search available is from the website. + +- The production site is well indexed. +- Local intra-site search available is from the website. **Account custodians** -* There are no records showing the different account custodians; nothing is listed on `MAINTAINERS.md` and no `OWNERS.md` is found. + +- There are no records showing the different account custodians; nothing is + listed on `MAINTAINERS.md` and no `OWNERS.md` is found. ### Maintenance planning -The website uses Hugo and Docsy, which are the recommended **website tooling** for CNCF projects. +The website uses Hugo and Docsy, which are the recommended **website tooling** +for CNCF projects. -There is no sign that the project is **cultivating website maintainers** from the community. However, the site is small and much of the content is links to community or third-party scalers (plugin components). +There is no sign that the project is **cultivating website maintainers** from +the community. However, the site is small and much of the content is links to +community or third-party scalers (plugin components). **Build times** for the website are minimal. -Presumably, **site maintainers have adequate permissions** since the documentation is up to date with the software. - +Presumably, **site maintainers have adequate permissions** since the +documentation is up to date with the software. ### Other -The website is accessible via **HTTPS**. Requests using **HTTP** are properly redirected to the **HTTPS** URLs. - +The website is accessible via **HTTPS**. Requests using **HTTP** are properly +redirected to the **HTTPS** URLs. ## Recommendations @@ -380,38 +509,37 @@ No recommendations. ### Minimal website requirements -Identify stakeholder roles in the user documentation (even if there is only one role). This could be as minimal as a "who should use this documentation" paragraph in the product introduction. - -Update docs per Implementation and Issues recommendations (separate documents). Especially, improve new user documentation. +Identify stakeholder roles in the user documentation (even if there is only one +role). This could be as minimal as a "who should use this documentation" +paragraph in the product introduction. +Update docs per Implementation and Issues recommendations (separate documents). +Especially, improve new user documentation. ### Usability, accessibility and devices No recommendations. - ### Branding and design No recommendations. - ### Case studies/social proof No recommendations. - ### SEO, Analytics and site-local search -The current custodian(s) of the following accounts should be clearly documented: analytics (GA4), site-search (Algolia). You can create an `OWNERS.md` file for this. +The current custodian(s) of the following accounts should be clearly documented: +analytics (GA4), site-search (Algolia). You can create an `OWNERS.md` file for +this. ### Maintenance planning Explicitly list and solicit maintainers and contributors for documentation. - ### Other No recommendations. - diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index 7b777fa..552d69e 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -5,15 +5,27 @@ tags: keda # Introduction -This document provides actionable suggestions for improving the KEDA technical documentaiton. +This document provides actionable suggestions for improving the KEDA technical +documentaiton. -For an analysis and general discussion of recommendations on KEDA technical documentation, see [keda-analysis.md][keda-analysis]. +For an analysis and general discussion of recommendations on KEDA technical +documentation, see [keda-analysis.md][keda-analysis]. ## 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. +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 documentation recommendations for this project are: + - [Reorganize the table of contents (TOC)](#reorganize-the-table-of-contents-toc) - [Write a glossary](#write-a-glossary) - [Add "How to set up a scaler" to the Operator guide](#add-how-to-set-up-a-scaler-to-the-operator-guide) @@ -23,7 +35,6 @@ The documentation recommendations for this project are: - [Make user roles explicit](#make-user-roles-explicit) - [Clarify documentation maintainers](#clarify-documentation-maintainers) - # Reorganize the Table of Contents Reorganize the Table of Contents to: @@ -34,10 +45,17 @@ Reorganize the Table of Contents to: - Separate conceptual, task, and reference information In general, follow these principles when reorganizing the documentation: -- Put architecture, operating principles, and other conceptual explanations in the technical overview. -- Write instructions (in "Using KEDA" and "Getting Started") as step-by-step procedures. Title each procedure using "-ing" verbs; for example "Integrating", "Using", "Migrating". -- Put purely reference information in the Reference section. Link to this information where relevant from the procedures in the "Using KEDA" and "Getting Started" sections. -- Separate and/or label information, especially tasks, by which user role it pertains to (again, if more than one). + +- Put architecture, operating principles, and other conceptual explanations in + the technical overview. +- Write instructions (in "Using KEDA" and "Getting Started") as step-by-step + procedures. Title each procedure using "-ing" verbs; for example + "Integrating", "Using", "Migrating". +- Put purely reference information in the Reference section. Link to this + information where relevant from the procedures in the "Using KEDA" and + "Getting Started" sections. +- Separate and/or label information, especially tasks, by which user role it + pertains to (again, if more than one). - Include a clear starting point and ramp-up path for new users. Here is a proposed outline for the tech doc Table of Contents: @@ -55,7 +73,8 @@ Here is a proposed outline for the tech doc Table of Contents: - [Authentication](/docs/2.13/concepts/authentication/) - [External Scalers](/docs/2.13/concepts/external-scalers/) - [Admission Webhooks](/docs/2.13/concepts/admission-webhooks/) -- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA Documentation" heading) +- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA + Documentation" heading) - [Deploying KEDA](/docs/2.13/deploy/) - Prerequisites (https://keda.sh/docs/2.13/operate/cluster/#requirements) - [Deploying with Helm](#helm) @@ -70,17 +89,22 @@ Here is a proposed outline for the tech doc Table of Contents: - [Deploying KEDA on MicroK8s](#microk8s) - [Installing](#install-3) - [Uninstalling](#uninstall-3) - - Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like https://github.com/kedacore/sample-hello-world-azure-functions) + - Hello, KEDA (write a procedure for a simplest-possible use case for users to + get started on - something like + https://github.com/kedacore/sample-hello-world-azure-functions) - [Using KEDA or Operator Guide](/docs/2.13/operate/) (rename current "Operate") - - How to set up a scaler (a more detailed procedure than the example used in Getting Started) + - How to set up a scaler (a more detailed procedure than the example used in + Getting Started) - Usage Scenarios - [Scaling with RabbitMQ and Go](https://github.com/kedacore/sample-go-rabbitmq) - [Scaling with Azure Functions and Kafka on Openshift 4](https://github.com/kedacore/sample-azure-functions-on-ocp4) - ... and so on. - [Admission Webhooks](/docs/2.13/operate/admission-webhooks/) - - Prevention Rules (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules) + - Prevention Rules + (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules) - Validation Enforcement - - [Cluster](/docs/2.13/operate/cluster/) - Except sections that are purely reference info, for example: + - [Cluster](/docs/2.13/operate/cluster/) - Except sections that are purely + reference info, for example: - https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility - https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity - https://keda.sh/docs/2.13/operate/cluster/#firewall @@ -90,18 +114,25 @@ Here is a proposed outline for the tech doc Table of Contents: - [Querying Metrics](https://keda.sh/docs/2.13/operate/metrics-server/#querying-metrics-exposed-by-keda-metrics-server) - [Getting Metric Names](https://keda.sh/docs/2.13/operate/metrics-server/#how-to-get-metric-names-from-scaledobject) - [Security](/docs/2.13/operate/security/) - - [Migrating to a new release](/docs/2.13/migration/) (current "Migration Guide") - - Caching Metrics (https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics) - - Pausing Autoscaling of deployments (https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling) - - Pausing Autoscaling of jobs (https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling) - - [Troubleshooting](/docs/2.13/concepts/troubleshooting/, /docs/2.13/troubleshooting/) + - [Migrating to a new release](/docs/2.13/migration/) (current "Migration + Guide") + - Caching Metrics + (https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics) + - Pausing Autoscaling of deployments + (https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling) + - Pausing Autoscaling of jobs + (https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling) + - [Troubleshooting](/docs/2.13/concepts/troubleshooting/, + /docs/2.13/troubleshooting/) - Reference - [Authentication Providers](/docs/2.13/authentication-providers/) - [AWS (IRSA) Pod Identity Webhook](/docs/2.13/authentication-providers/aws/) - ... - [Secret](/docs/2.13/authentication-providers/secret/) - - Scaled Object specification (from "Concepts"; https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec) - - ScaledJob specification (https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec) + - Scaled Object specification (from "Concepts"; + https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec) + - ScaledJob specification + (https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec) - [Events](/docs/2.13/operate/events/) - [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall) - ... @@ -120,7 +151,8 @@ Among other things, the reorganization includes these changes: - Add a glossary to the Reference section. - Rename "Operate" to "Operator Guide". - Move "Troubleshooting" to the end of the User Guide. -- Separate reference and task information that appears on the same page and move each to the appropriate section. +- Separate reference and task information that appears on the same page and move + each to the appropriate section. # Write a Glossary @@ -128,59 +160,96 @@ Create a glossary of terms specific to KEDA. Add to the Reference section. # Add "How to set up a scaler" to the Operator guide -Setting up a scaler seems to be largely a matter of installing the scaler and providing parameters in a configuration file. While the configurations are provided for all the various scalers, there doesn't seem to be a description of the procedure for doing the basic setup. This should go at the top of the Operator guide. Users should be able to follow the procedure for any (or at least most) scalers. +Setting up a scaler seems to be largely a matter of installing the scaler and +providing parameters in a configuration file. While the configurations are +provided for all the various scalers, there doesn't seem to be a description of +the procedure for doing the basic setup. This should go at the top of the +Operator guide. Users should be able to follow the procedure for any (or at +least most) scalers. -Any scaler that requires special instructions other than the configuration file should have its own procedure page, listing the extra steps required. +Any scaler that requires special instructions other than the configuration file +should have its own procedure page, listing the extra steps required. # Write a New User workflow -Write a task-based, step-by-step workflow for new users. Assume the new user has no experience with KEDA and is fairly new to Kubernetes. - -The current documentation assumes that users know how to deploy and use Kubernetes Custom Resources, and that using KEDA is a matter of knowing the right configuration parameters and deploying the right resources. This might be true for veteran users, but new users want explicit, foolproof instructions. The following outline, extracted from the proposed outline in [Reorganize the Table of Contents](#reorganize-the-table-of-contents), has been annotated to illustrate this point: - -* [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA Documentation" heading) *Make the new user entry point obvious* - * [Deploying KEDA](/docs/2.13/deploy/) *This is analogous to "Install" for application software or a plugin. It's the starting point for a new user.* - * [Prerequisites](https://keda.sh/docs/2.13/operate/cluster/#requirements) *Make sure the new user has their tools gathered up before they start. This reduces frustration. Next, what is the advantage of one deployment method over another? If the choice is not completely arbitrary, explain the differences here to help the new user decide. Also, if prerequisites depend on the deployment type, you can optionally put a Prerequisites section in each deployment procedure rather than here.* - * [Deploying with Helm](#helm) - - [Installing](#install) - - [Uninstalling](#uninstall) * - * [Deploying with Operator Hub](#operatorhub) - - [Installing](#install-1) - - [Uninstalling](#uninstall-1) - * [Deploying using the deployment YAML files](#yaml) - - [Installing](#install-2) - - [Uninstalling](#uninstall-2) - * [Deploying KEDA on MicroK8s](#microk8s) - - [Installing](#install-3) - - [Uninstalling](#uninstall-3) - * Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like https://github.com/kedacore/sample-hello-world-azure-functions) *analogous to a "Hello World" exercise in programming language or API guides* - +Write a task-based, step-by-step workflow for new users. Assume the new user has +no experience with KEDA and is fairly new to Kubernetes. + +The current documentation assumes that users know how to deploy and use +Kubernetes Custom Resources, and that using KEDA is a matter of knowing the +right configuration parameters and deploying the right resources. This might be +true for veteran users, but new users want explicit, foolproof instructions. The +following outline, extracted from the proposed outline in +[Reorganize the Table of Contents](#reorganize-the-table-of-contents), has been +annotated to illustrate this point: + +- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA + Documentation" heading) _Make the new user entry point obvious_ + - [Deploying KEDA](/docs/2.13/deploy/) _This is analogous to "Install" for + application software or a plugin. It's the starting point for a new user._ + - [Prerequisites](https://keda.sh/docs/2.13/operate/cluster/#requirements) + _Make sure the new user has their tools gathered up before they start. + This reduces frustration. Next, what is the advantage of one deployment + method over another? If the choice is not completely arbitrary, explain + the differences here to help the new user decide. Also, if prerequisites + depend on the deployment type, you can optionally put a Prerequisites + section in each deployment procedure rather than here._ + - [Deploying with Helm](#helm) + - [Installing](#install) + - [Uninstalling](#uninstall) \* + - [Deploying with Operator Hub](#operatorhub) + - [Installing](#install-1) + - [Uninstalling](#uninstall-1) + - [Deploying using the deployment YAML files](#yaml) + - [Installing](#install-2) + - [Uninstalling](#uninstall-2) + - [Deploying KEDA on MicroK8s](#microk8s) + - [Installing](#install-3) + - [Uninstalling](#uninstall-3) + - Hello, KEDA (write a procedure for a simplest-possible use case for users to + get started on - something like + https://github.com/kedacore/sample-hello-world-azure-functions) _analogous + to a "Hello World" exercise in programming language or API guides_ # Update the doc content creation instructions -In the keda-docs [README](https://github.com/kedacore/keda-docs/blob/main/README.md): -- Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial offering!" sections into their own files, or move them to the bottom of the README, so they're not at the top of the keda-docs README. -- Combine "Adding scaler documentation" and "Writing documentation for a scaler" so that they're not separated by "Writing documentation for a new authentication provider". +In the keda-docs +[README](https://github.com/kedacore/keda-docs/blob/main/README.md): + +- Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial + offering!" sections into their own files, or move them to the bottom of the + README, so they're not at the top of the keda-docs README. +- Combine "Adding scaler documentation" and "Writing documentation for a scaler" + so that they're not separated by "Writing documentation for a new + authentication provider". -Document in the repo (keda-docs, keda, or both) who the website/documentation maintainers are. +Document in the repo (keda-docs, keda, or both) who the website/documentation +maintainers are. # Remove non-inclusive language -Remove non-inclusive language throughout the documentation as recommended by the [Inclusive Naming Initiative](https://inclusivenaming.org/). +Remove non-inclusive language throughout the documentation as recommended by the +[Inclusive Naming Initiative](https://inclusivenaming.org/). # Make user roles explicit -KEDA seems to have only one explicit user role (or *persona*), namely, an Operator using KEDA to scale resources on a Kubernetes installation. Regardless, this user role should be explicitly distinguished from the project Contributor user role. Use cases are different between the two roles. One strategy for separating the documentation is to confine the Contributor docs to the GitHub repo. - -The definition of the Operator role could be as minimal as a "who should use this documentation" paragraph in the product introduction. +KEDA seems to have only one explicit user role (or _persona_), namely, an +Operator using KEDA to scale resources on a Kubernetes installation. Regardless, +this user role should be explicitly distinguished from the project Contributor +user role. Use cases are different between the two roles. One strategy for +separating the documentation is to confine the Contributor docs to the GitHub +repo. +The definition of the Operator role could be as minimal as a "who should use +this documentation" paragraph in the product introduction. # Clarify documentation maintainers -Create an `OWNERS.md` file to document (on the repo) the current custodian(s) of the following accounts: analytics (GA4), site-search (Algolia). - -Explicitly list and solicit maintainers and contributors for documentation, either in the new OWNERS file or the governance MAINTAINERS file. +Create an `OWNERS.md` file to document (on the repo) the current custodian(s) of +the following accounts: analytics (GA4), site-search (Algolia). +Explicitly list and solicit maintainers and contributors for documentation, +either in the new OWNERS file or the governance MAINTAINERS file. diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index 95673c8..512b9a4 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -6,7 +6,9 @@ cSpell:ignore: findability # Overview -This document outlines the recommended changes to the KEDA documentation. The following issues are added to the [project repo](https://github.com/kedacore/keda-docs). +This document outlines the recommended changes to the KEDA documentation. The +following issues are added to the +[project repo](https://github.com/kedacore/keda-docs). # Issue: Reorganize the Table of Contents @@ -17,20 +19,26 @@ Reorganize the Table of Contents to: - Improve findability and access to tasks and procedures - Separate conceptual, task, and reference information -Here is a proposed high-level outline for the tech doc Table of Contents. Work on individual sections is broken out into sub-issues. - -- [KEDA Concepts](https://keda.sh/docs/2.13/concepts/). See [Reorganize Concepts](#issue-reorganize-concepts). -- [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename current "KEDA Documentation" heading). See [Write a "Getting Started" Guide](#issue-write-a-getting-started-guide). -- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename current "Operate"). See [Update the Operator Guide](#issue-update-the-operator-guide). +Here is a proposed high-level outline for the tech doc Table of Contents. Work +on individual sections is broken out into sub-issues. + +- [KEDA Concepts](https://keda.sh/docs/2.13/concepts/). See + [Reorganize Concepts](#issue-reorganize-concepts). +- [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename + current "KEDA Documentation" heading). See + [Write a "Getting Started" Guide](#issue-write-a-getting-started-guide). +- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename + current "Operate"). See + [Update the Operator Guide](#issue-update-the-operator-guide). - Reference. See [Create a Reference](#issue-create-a-reference-topic). - [Scalers](https://keda.sh/docs/2.13/scalers/). - ## Issue: Reorganize Concepts Remove everything that's not a conceptual overview. -Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point. +Here is a proposed outline. Links are to existing pages that can be used as-is +or provide a starting point. - [KEDA Concepts](https://keda.sh/docs/2.13/concepts/) - What is KEDA? @@ -46,33 +54,51 @@ Here is a proposed outline. Links are to existing pages that can be used as-is o - [External Scalers](https://keda.sh/docs/2.13/concepts/external-scalers/) - [Admission Webhooks](https://keda.sh/docs/2.13/concepts/admission-webhooks/) - ## Issue: Write a "Getting Started" guide -Write a task-based, step-by-step workflow for new users. Start with the current "KEDA Documentation" section. - -Assume the new user has no experience with KEDA and is fairly new to Kubernetes. The current documentation assumes that users know how to deploy and use Kubernetes Custom Resources, and that using KEDA is a matter of knowing the right configuration parameters and deploying the right resources. This might be true for veteran users, but new users want explicit, foolproof instructions. - -The following outline has been annotated to illustrate this point. Links are to existing pages that can be used as-is or provide a starting point. Pages with multiple procedures (for example, the "Deploying KEDA" page) should be split into multiple pages, one for each procedure. - -- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA Documentation" heading) *Make the new user entry point obvious.* - - [Deploying KEDA](/docs/2.13/deploy/) *This is analogous to "Install" for application software or a plugin. It's the starting point for a new user.* - - Overview *Briefly explain the differences between installation methods. What is the advantage of one deployment method over another? If the choice is not completely arbitrary, explain the differences here to help the new user decide.* - - [Prerequisites](https://keda.sh/docs/2.13/operate/cluster/#requirements) *Make sure the new user has their tools gathered up before they start. This reduces frustration. Also, if prerequisites depend on the deployment type, you can optionally put a Prerequisites section in each deployment procedure rather than here.* +Write a task-based, step-by-step workflow for new users. Start with the current +"KEDA Documentation" section. + +Assume the new user has no experience with KEDA and is fairly new to Kubernetes. +The current documentation assumes that users know how to deploy and use +Kubernetes Custom Resources, and that using KEDA is a matter of knowing the +right configuration parameters and deploying the right resources. This might be +true for veteran users, but new users want explicit, foolproof instructions. + +The following outline has been annotated to illustrate this point. Links are to +existing pages that can be used as-is or provide a starting point. Pages with +multiple procedures (for example, the "Deploying KEDA" page) should be split +into multiple pages, one for each procedure. + +- [Getting Started (New users start here!)](/docs/2.13/) (rename current "KEDA + Documentation" heading) _Make the new user entry point obvious._ + - [Deploying KEDA](/docs/2.13/deploy/) _This is analogous to "Install" for + application software or a plugin. It's the starting point for a new user._ + - Overview _Briefly explain the differences between installation methods. + What is the advantage of one deployment method over another? If the choice + is not completely arbitrary, explain the differences here to help the new + user decide._ + - [Prerequisites](https://keda.sh/docs/2.13/operate/cluster/#requirements) + _Make sure the new user has their tools gathered up before they start. + This reduces frustration. Also, if prerequisites depend on the deployment + type, you can optionally put a Prerequisites section in each deployment + procedure rather than here._ - [Deploying with Helm](#helm) - - [Installing](#install) - - [Uninstalling](#uninstall) + - [Installing](#install) + - [Uninstalling](#uninstall) - [Deploying with Operator Hub](#operatorhub) - - [Installing](#install-1) - - [Uninstalling](#uninstall-1) + - [Installing](#install-1) + - [Uninstalling](#uninstall-1) - [Deploying using the deployment YAML files](#yaml) - - [Installing](#install-2) - - [Uninstalling](#uninstall-2) + - [Installing](#install-2) + - [Uninstalling](#uninstall-2) - [Deploying KEDA on MicroK8s](#microk8s) - - [Installing](#install-3) - - [Uninstalling](#uninstall-3) - - Hello, KEDA (write a procedure for a simplest-possible use case for users to get started on - something like https://github.com/kedacore/sample-hello-world-azure-functions) *analogous to a "Hello World" exercise in programming language or API guides* - + - [Installing](#install-3) + - [Uninstalling](#uninstall-3) + - Hello, KEDA (write a procedure for a simplest-possible use case for users to + get started on - something like + https://github.com/kedacore/sample-hello-world-azure-functions) _analogous + to a "Hello World" exercise in programming language or API guides_ ## Issue: Update the Operator Guide @@ -81,24 +107,34 @@ Some guidelines: - Can be named "Using KEDA" or "Operator Guide". - Base the guide on the existing "Operator" section. - Move "Troubleshooting" to the end of the Operator Guide. -- Relocate sections that are purely reference information, including these sections in [Cluster](https://keda.sh/docs/2.13/operate/cluster/): +- Relocate sections that are purely reference information, including these + sections in [Cluster](https://keda.sh/docs/2.13/operate/cluster/): - https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility - https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity - https://keda.sh/docs/2.13/operate/cluster/#firewall -- Break up long pages containing several topics. Aim for one major topic per page. For example, all HTTP-related headings on the [Cluster](https://keda.sh/docs/2.13/operate/cluster/) page could go on one page named "Using HTTP". - -Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point. - -- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename current "Operate") - - Setting up a scaler (write or adapt a more detailed procedure than the example used in Getting Started - see ["Write 'Setting Up a Scaler'"](#write-setting-up-a-scaler)) +- Break up long pages containing several topics. Aim for one major topic per + page. For example, all HTTP-related headings on the + [Cluster](https://keda.sh/docs/2.13/operate/cluster/) page could go on one + page named "Using HTTP". + +Here is a proposed outline. Links are to existing pages that can be used as-is +or provide a starting point. + +- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename + current "Operate") + - Setting up a scaler (write or adapt a more detailed procedure than the + example used in Getting Started - see + ["Write 'Setting Up a Scaler'"](#write-setting-up-a-scaler)) - Usage Scenarios - [Scaling with RabbitMQ and Go](https://github.com/kedacore/sample-go-rabbitmq) - [Scaling with Azure Functions and Kafka on Openshift 4](https://github.com/kedacore/sample-azure-functions-on-ocp4) - ... and so on. - [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/) - - Prevention Rules (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules) + - Prevention Rules + (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules) - Validation Enforcement - - [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - (Relocate sections that are purely reference info) + - [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - (Relocate sections + that are purely reference info) - Using HTTP [Setting Timeouts](https://keda.sh/docs/2.13/operate/cluster/#http-timeouts) [Disabling Keep-alive](https://keda.sh/docs/2.13/operate/cluster/#http-connection-disable-keep-alive) @@ -110,12 +146,16 @@ Here is a proposed outline. Links are to existing pages that can be used as-is o - [Querying Metrics](https://keda.sh/docs/2.13/operate/metrics-server/#querying-metrics-exposed-by-keda-metrics-server) - [Getting Metric Names](https://keda.sh/docs/2.13/operate/metrics-server/#how-to-get-metric-names-from-scaledobject) - [Security](https://keda.sh/docs/2.13/operate/security/) - - [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current "Migration Guide") - - Caching Metrics (https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics) - - Pausing Autoscaling of deployments (https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling) - - Pausing Autoscaling of jobs (https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling) - - [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/, /docs/2.13/troubleshooting/) - + - [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current + "Migration Guide") + - Caching Metrics + (https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics) + - Pausing Autoscaling of deployments + (https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling) + - Pausing Autoscaling of jobs + (https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling) + - [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/, + /docs/2.13/troubleshooting/) ## Issue: Create a "Reference" topic @@ -124,47 +164,58 @@ Here is a proposed outline. Links are to existing pages that can be used as-is o - Move the FAQ to the Reference section. - Add a glossary to the Reference section. -Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point. +Here is a proposed outline. Links are to existing pages that can be used as-is +or provide a starting point. - Reference - [Authentication Providers](https://keda.sh/docs/2.13/authentication-providers/) - [AWS (IRSA) Pod Identity Webhook](https://keda.sh/docs/2.13/authentication-providers/aws/) - ... - [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/) - - Scaled Object specification (from "Concepts"; https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec) - - ScaledJob specification (https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec) + - Scaled Object specification (from "Concepts"; + https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec) + - ScaledJob specification + (https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec) - [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/) - Glossary - # Separate reference and task information -A common practice that reduces documentation effectiveness is mixing conceptual and task information. *Conceptual* discussion can be thought of as *How it works*; a *Task* is *How you use it*. Tasks should be described step-by-step as explicitly as possible. - -Reference information is also embedded sometimes, but in general is easy to extract. - -In pages where conceptual, reference, and/or task info appears on the same page, separate and move each to the appropriate section. - -Here is a list of some of the KEDA pages containing more than one type of information. Some of these pages might appear in other issues suggesting that they be revised or relocated. If this creates contradictory recommendations, some judgement might be required to rearrange things. - -| Page Title | URL | Notes | -| --- | --- | --- | -| Deploying KEDA | https://keda.sh/docs/2.13/deploy/ | Page is all install and uninstall tasks, but put each install procedure on its own page. Make this page an intro and index. | -| Scaling Deployments, StatefulSets and Custom Resources | https://keda.sh/docs/2.13/concepts/scaling-deployments/ | The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task. | -| Scaling Jobs | https://keda.sh/docs/2.13/concepts/scaling-jobs/ | "ScaledJob spec" is reference information. | -| Authentication | https://keda.sh/docs/2.13/concepts/authentication/ | Deliberately discuss the three patterns listed at the top of the page. This entire page might be better written as a task-based how-to guide. | -| External Scalers | https://keda.sh/docs/2.13/concepts/external-scalers/ | "Implementing KEDA external scaler GRPC interface" is a series of tasks. The steps after the first 2 are choices -- Describe the task of downloading `externalscaler.proto` and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently. | -| Troubleshooting | https://keda.sh/docs/2.13/concepts/troubleshooting/ | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". | -| Cluster | https://keda.sh/docs/2.13/operate/cluster/ | See the "Update the Operator Guide" issue | -| Events | https://keda.sh/docs/2.13/operate/events/ | This is reference information. | -| Integrate with Prometheus | https://keda.sh/docs/2.13/operate/prometheus/ | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". | +A common practice that reduces documentation effectiveness is mixing conceptual +and task information. _Conceptual_ discussion can be thought of as _How it +works_; a _Task_ is _How you use it_. Tasks should be described step-by-step as +explicitly as possible. + +Reference information is also embedded sometimes, but in general is easy to +extract. + +In pages where conceptual, reference, and/or task info appears on the same page, +separate and move each to the appropriate section. + +Here is a list of some of the KEDA pages containing more than one type of +information. Some of these pages might appear in other issues suggesting that +they be revised or relocated. If this creates contradictory recommendations, +some judgement might be required to rearrange things. + +| Page Title | URL | Notes | +| ------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Deploying KEDA | https://keda.sh/docs/2.13/deploy/ | Page is all install and uninstall tasks, but put each install procedure on its own page. Make this page an intro and index. | +| Scaling Deployments, StatefulSets and Custom Resources | https://keda.sh/docs/2.13/concepts/scaling-deployments/ | The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task. | +| Scaling Jobs | https://keda.sh/docs/2.13/concepts/scaling-jobs/ | "ScaledJob spec" is reference information. | +| Authentication | https://keda.sh/docs/2.13/concepts/authentication/ | Deliberately discuss the three patterns listed at the top of the page. This entire page might be better written as a task-based how-to guide. | +| External Scalers | https://keda.sh/docs/2.13/concepts/external-scalers/ | "Implementing KEDA external scaler GRPC interface" is a series of tasks. The steps after the first 2 are choices -- Describe the task of downloading `externalscaler.proto` and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently. | +| Troubleshooting | https://keda.sh/docs/2.13/concepts/troubleshooting/ | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". | +| Cluster | https://keda.sh/docs/2.13/operate/cluster/ | See the "Update the Operator Guide" issue | +| Events | https://keda.sh/docs/2.13/operate/events/ | This is reference information. | +| Integrate with Prometheus | https://keda.sh/docs/2.13/operate/prometheus/ | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". | # Write a Glossary -Create a glossary of terms specific to KEDA. It wouldn't hurt to include some key Kubernetes terms as well, especially acronyms. Add to the Reference section. +Create a glossary of terms specific to KEDA. It wouldn't hurt to include some +key Kubernetes terms as well, especially acronyms. Add to the Reference section. Here is a partial list of terms to include: @@ -189,45 +240,70 @@ Here is a partial list of terms to include: - TLS - Webhook -For an example from another CNCF project, see the [glossary in the Backstage documentation](https://backstage.io/docs/references/glossary/). +For an example from another CNCF project, see the +[glossary in the Backstage documentation](https://backstage.io/docs/references/glossary/). # Write "Setting Up a Scaler" -Setting up a scaler seems to be largely a matter of installing the scaler and providing parameters in a configuration file. While the configurations are provided for all the various scalers, there doesn't seem to be a description of the procedure for doing the basic setup. This should go at the top of the Operator guide. - -Users should be able to follow the procedure for any (or at least most) scalers. Any scaler that requires special instructions other than the configuration file should have its own procedure page, listing the extra steps required. +Setting up a scaler seems to be largely a matter of installing the scaler and +providing parameters in a configuration file. While the configurations are +provided for all the various scalers, there doesn't seem to be a description of +the procedure for doing the basic setup. This should go at the top of the +Operator guide. +Users should be able to follow the procedure for any (or at least most) scalers. +Any scaler that requires special instructions other than the configuration file +should have its own procedure page, listing the extra steps required. # Make user roles explicit -KEDA seems to have only one explicit user role (or *persona*), namely, an Operator using KEDA to scale resources on a Kubernetes installation. Regardless, this user role should be explicitly distinguished from the project Contributor user role. Use cases are different between the two roles. One strategy for separating the documentation is to confine the Contributor docs to the GitHub repo. - -The definition of the Operator role could be as minimal as a "who should use this documentation" paragraph in the product introduction. +KEDA seems to have only one explicit user role (or _persona_), namely, an +Operator using KEDA to scale resources on a Kubernetes installation. Regardless, +this user role should be explicitly distinguished from the project Contributor +user role. Use cases are different between the two roles. One strategy for +separating the documentation is to confine the Contributor docs to the GitHub +repo. +The definition of the Operator role could be as minimal as a "who should use +this documentation" paragraph in the product introduction. # Update the doc content creation instructions -Make the following changes to improve the effectiveness of the KEDA documentation contributor instructions. +Make the following changes to improve the effectiveness of the KEDA +documentation contributor instructions. -In the keda-docs [README](https://github.com/kedacore/keda-docs/blob/main/README.md): -- Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial offering!" sections into their own files, or move them to the bottom of the README, so they're not at the top of the keda-docs README. -- Combine "Adding scaler documentation" and "Writing documentation for a scaler" so that they're not separated by "Writing documentation for a new authentication provider". +In the keda-docs +[README](https://github.com/kedacore/keda-docs/blob/main/README.md): +- Move the "Become a listed KEDA user!" and "Become a listed KEDA commercial + offering!" sections into their own files, or move them to the bottom of the + README, so they're not at the top of the keda-docs README. +- Combine "Adding scaler documentation" and "Writing documentation for a scaler" + so that they're not separated by "Writing documentation for a new + authentication provider". # Clarify the KEDA website and documentation maintainers -Create an `OWNERS.md` file to document (on the kedacore/keda-docs repo) the current custodian(s) of the following accounts: analytics (GA4), site-search (Algolia). - -Explicitly document in the repo (keda-docs, keda, or both) who the website/documentation maintainers are. Solicit maintainers and contributors for documentation, either in the new OWNERS file or the governance MAINTAINERS file. +Create an `OWNERS.md` file to document (on the kedacore/keda-docs repo) the +current custodian(s) of the following accounts: analytics (GA4), site-search +(Algolia). +Explicitly document in the repo (keda-docs, keda, or both) who the +website/documentation maintainers are. Solicit maintainers and contributors for +documentation, either in the new OWNERS file or the governance MAINTAINERS file. # Remove non-inclusive language -Remove non-inclusive language throughout the documentation as recommended by the [Inclusive Naming Initiative](https://inclusivenaming.org/). Some examples of non-inclusive language in KEDA: - -- In [concepts/scaling-deployments.md](https://keda.sh/docs/2.13/concepts/scaling-deployments/): "This value can be used to easily distinguish this specific trigger and its metrics ..." -- The use of "master" (as in "sentinelMaster") in [scalers/redis-sentinel-lists.md](https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/). This might be impossible to change without changing the Redis scaler as well.) -- In [deploy.md](https://keda.sh/docs/2.13/deploy/): "Deploying KEDA with Helm is very simple". - - - +Remove non-inclusive language throughout the documentation as recommended by the +[Inclusive Naming Initiative](https://inclusivenaming.org/). Some examples of +non-inclusive language in KEDA: + +- In + [concepts/scaling-deployments.md](https://keda.sh/docs/2.13/concepts/scaling-deployments/): + "This value can be used to easily distinguish this specific trigger and its + metrics ..." +- The use of "master" (as in "sentinelMaster") in + [scalers/redis-sentinel-lists.md](https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/). + This might be impossible to change without changing the Redis scaler as well.) +- In [deploy.md](https://keda.sh/docs/2.13/deploy/): "Deploying KEDA with Helm + is very simple". diff --git a/analyses/README.md b/analyses/README.md index 7c48309..1ca657d 100644 --- a/analyses/README.md +++ b/analyses/README.md @@ -6,31 +6,61 @@ The goals of a CNCF technical documentation analysis are to: -- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](../docs/analysis/criteria.md). -- Compare the documentation against the current or proposed maturity level for the overall project. -- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](../docs/analysis/resources/implementation-template.md) and [issues backlog](../docs/analysis/resources/umbrella-issue-template.md). +- Examine the current project technical documentation and website against the + CNCF's analysis framework, as described in the doc analysis + [criteria](../docs/analysis/criteria.md). +- Compare the documentation against the current or proposed maturity level for + the overall project. +- Recommends a program of key improvements with the largest return on + investment. These improvements are documented as _recommendations_ in the + analysis document and expanded in a companion + [implementation plan](../docs/analysis/resources/implementation-template.md) + and [issues backlog](../docs/analysis/resources/umbrella-issue-template.md). ## Audience -Analyses are written for the purpose of improving a project's documentation and are available for anyone to read. Among the intended benefits to project stakeholders are these: +Analyses are written for the purpose of improving a project's documentation and +are available for anyone to read. Among the intended benefits to project +stakeholders are these: -- **Project maintainers** can gain a critical overview of the technical documentation to plan work on the project's documentation. This work can increase the effectiveness of the project software, speed adoption, and improve user satisfaction. -- **Project contributors** can take on the recommended backlog issues to improve the documentation. +- **Project maintainers** can gain a critical overview of the technical + documentation to plan work on the project's documentation. This work can + increase the effectiveness of the project software, speed adoption, and + improve user satisfaction. +- **Project contributors** can take on the recommended backlog issues to improve + the documentation. -The analyses also provide information of value to organizations with an interest in promoting open source software: +The analyses also provide information of value to organizations with an interest +in promoting open source software: -- **CNCF Foundation members** can see what benefits can (and cannot) be expected of a documentation improvement effort. -- **Members of other open-source software foundations** can use these analyses as a model for their own documentation improvement processes. (Please contact the Cloud Native Computing Foundation to discuss licensing and permission of analysis templates and tools.) +- **CNCF Foundation members** can see what benefits can (and cannot) be expected + of a documentation improvement effort. +- **Members of other open-source software foundations** can use these analyses + as a model for their own documentation improvement processes. (Please contact + the Cloud Native Computing Foundation to discuss licensing and permission of + analysis templates and tools.) ## Contents -This directory contains completed analyses of the technical documentation for selected CNCF incubating and graduated software projects. +This directory contains completed analyses of the technical documentation for +selected CNCF incubating and graduated software projects. -The analyses are in one of two formats depending on when they were written. Earlier analyses (**0001** - **0007**) are Markdown files, each of which is the sole artifact of the analysis. +The analyses are in one of two formats depending on when they were written. +Earlier analyses (**0001** - **0007**) are Markdown files, each of which is the +sole artifact of the analysis. -Subsequent analyses (**0008-** forward) each has its own directory containing three analysis artifacts: - - `projectname-analysis.md` evaluates the project documentation and provides comments and recommendations in a manner very similar to the Round 1 tech doc assessments. This document is based on the analysis template and accompanying criteria developed for the Round 1. - - `projectname-implementation.md` provides concrete actions that can be implemented by project contributors. Its focus is on specific, achievable work that will have a strong positive impact on document effectiveness. - - `projectname-issues.md` is a backlog of improvement actions, meant to be entered as GitHub Issues, derived from `projectname-implementation.md`. +Subsequent analyses (**0008-** forward) each has its own directory containing +three analysis artifacts: -Each directory might also contain other documents, such as CSV-formatted surveys of documentation pages. +- `projectname-analysis.md` evaluates the project documentation and provides + comments and recommendations in a manner very similar to the Round 1 tech doc + assessments. This document is based on the analysis template and accompanying + criteria developed for the Round 1. +- `projectname-implementation.md` provides concrete actions that can be + implemented by project contributors. Its focus is on specific, achievable work + that will have a strong positive impact on document effectiveness. +- `projectname-issues.md` is a backlog of improvement actions, meant to be + entered as GitHub Issues, derived from `projectname-implementation.md`. + +Each directory might also contain other documents, such as CSV-formatted surveys +of documentation pages. diff --git a/docs/README.md b/docs/README.md index 6f832a2..9eec011 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,5 @@ -# CNCF Techdocs how-tos - -This directory contains documentation on how the CNCF TechDocs team does things. While its intent is for the CNCF TechDocs team's use, we encourage project maintainers to use these documents if you find them helpful! +# CNCF Techdocs how-tos +This directory contains documentation on how the CNCF TechDocs team does things. +While its intent is for the CNCF TechDocs team's use, we encourage project +maintainers to use these documents if you find them helpful! diff --git a/docs/analysis/README.md b/docs/analysis/README.md index 7c5e414..f6edd8f 100644 --- a/docs/analysis/README.md +++ b/docs/analysis/README.md @@ -2,7 +2,8 @@ ## Contents -This directory contains instructions and criteria for completing a documentation analysis, including a [how-to][] guide and analysis [criteria][]. +This directory contains instructions and criteria for completing a documentation +analysis, including a [how-to][] guide and analysis [criteria][]. Templates for the analyses are in the resources directory. diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index 258783b..613b8a8 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -4,69 +4,79 @@ ### Information architecture -The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: - -* Is there high level conceptual/“About” content? -Is the documentation feature complete? (i.e., each product feature is documented) -* Are there step-by-step instructions (tasks, tutorials) documented for features? -* Are there any key features which are documented but missing task documentation? -* Is the “happy path”/most common use case documented? -Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) -* If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) -* If the product exposes an API, is there a complete reference? -* Is content up to date and accurate? +The overall structure (pages/subpages/sections/subsections) of your project +documentation. We evaluate on the following: + +- Is there high level conceptual/“About” content? Is the documentation feature + complete? (i.e., each product feature is documented) +- Are there step-by-step instructions (tasks, tutorials) documented for + features? +- Are there any key features which are documented but missing task + documentation? +- Is the “happy path”/most common use case documented? Does task and tutorial + content demonstrate atomicity and isolation of concerns? (Are tasks clearly + named according to user goals?) +- If the documentation does not suffice, is there a clear escalation path for + users needing more help? (FAQ, Troubleshooting) +- If the product exposes an API, is there a complete reference? +- Is content up to date and accurate? Examples: -* https://prometheus.io/docs/ - +- https://prometheus.io/docs/ ### New user content -New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: +New users are the most avid users of documentation, and need content +specifically for them. We evaluate on the following: -* Is “getting started” clearly labeled? (“Getting started”, “Installation”, “First steps”, etc.) -* Is installation documented step-by-step? -* If needed, are multiple OSes documented? -* Do users know where to go after reading the getting started guide? -* Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? -* Is there easily copy-pastable sample code or other example content? +- Is “getting started” clearly labeled? (“Getting started”, “Installation”, + “First steps”, etc.) +- Is installation documented step-by-step? +- If needed, are multiple OSes documented? +- Do users know where to go after reading the getting started guide? +- Is your new user content clearly signposted on your site’s homepage or at the + top of your information architecture? +- Is there easily copy-pastable sample code or other example content? Examples: -* https://falco.org/docs/getting-started/ - +- https://falco.org/docs/getting-started/ ### Content maintainability & site mechanics -As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. +As a project scales, concerns like localized (translated) content and versioning +become large maintenance burdens, particularly if you don’t plan for them. We evaluate on the following: -* Is your documentation searchable? -* Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? -* Do you have a clearly documented method for versioning your content? - +- Is your documentation searchable? +- Are you planning for localization/internationalization with regards to site + directory structure? Is a localization framework present? +- Do you have a clearly documented method for versioning your content? Examples: -* https://kubernetes.io/docs/ +- https://kubernetes.io/docs/ ### Content creation processes -Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. +Documentation is only as useful as it is accurate and well-maintained, and +requires the same kind of review and approval processes as code. We evaluate on the following: -* Is there a clearly documented (ongoing) contribution process for documentation? -* Does your code release process account for documentation creation & updates? -* Who reviews and approves documentation pull requests? -* Does the website have a clear owner/maintainer? +- Is there a clearly documented (ongoing) contribution process for + documentation? +- Does your code release process account for documentation creation & updates? +- Who reviews and approves documentation pull requests? +- Does the website have a clear owner/maintainer? Examples: -* https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly documented maintainers) -* https://thanos.io/tip/contributing/how-to-contribute-to-docs.md/ +- https://github.com/nats-io/nats-site/blob/master/MAINTAINERS.md (clearly + documented maintainers) +- https://thanos.io/tip/contributing/how-to-contribute-to-docs.md/ ### Inclusive language @@ -74,52 +84,61 @@ Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: -* Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website? -* Does the project use language like "simple", "easy", etc.? +- Are there any customer-facing utilities, endpoints, class names, or feature + names that use non-recommended words as documented by the + [Inclusive Naming Initiative](https://inclusivenaming.org) website? +- Does the project use language like "simple", "easy", etc.? ## Contributor documentation ### Communication methods documented -One of the easiest ways to attract new contributors is making sure they know how to reach you. +One of the easiest ways to attract new contributors is making sure they know how +to reach you. We evaluate on the following: -* Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? -* Is there a direct link to your GitHub organization/repository? -* Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? -* Are mailing lists documented? +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked + from your website? +- Is there a direct link to your GitHub organization/repository? +- Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings? +- Are mailing lists documented? Examples: -* https://prometheus.io/community/ +- https://prometheus.io/community/ ### Beginner friendly issue backlog We evaluate on the following: -* Are docs issues well-triaged? -* Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? -* Are issues well-documented (i.e., more than just a title)? -* Are issues maintained for staleness? +- Are docs issues well-triaged? +- Is there a clearly marked way for new contributors to make code or + documentation contributions (i.e. a “good first issue” label)? +- Are issues well-documented (i.e., more than just a title)? +- Are issues maintained for staleness? Examples: -* https://github.com/opentracing/opentracing.io/issues (all of open tracing’s backlogs are well maintained!) +- https://github.com/opentracing/opentracing.io/issues (all of open tracing’s + backlogs are well maintained!) ### New contributor getting started content -Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily? +Open source is complex and projects have many processes to manage that. Are +processes easy to understand and written down so that new contributors can jump +in easily? We evaluate on the following: -* 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? +- 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? Examples: -* https://github.com/helm/community +- https://github.com/helm/community ### Project governance documentation @@ -127,18 +146,19 @@ One of the CNCF’s core project values is open governance. We evaluate on the following: -* Is project governance clearly documented? +- Is project governance clearly documented? Examples: -* Any graduated CNCF project +- Any graduated CNCF project ## Website ### Single-source requirement -Source files for _all website pages_ should reside in a single repo. -Among other problems, keeping source files in two places: +Source files for _all website pages_ should reside in a single repo. Among other +problems, keeping source files in two places: + - confuses contributors - requires you to keep two sources in sync - increases the likelihood of errors @@ -161,7 +181,8 @@ maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. - **Sandbox** - - [Website guidelines](../../docs/website-guidelines-checklist.md): majority of the guidelines are satisfied + - [Website guidelines](../../docs/website-guidelines-checklist.md): 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 @@ -189,9 +210,11 @@ requirements for sandbox projects. - If a successor project exists, link to it's website and/or migration documentation. -[archived state]: https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories +[archived state]: + https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories [docs assessment]: ./howto.md -[maturity level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[maturity level]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [service desk]: https://servicedesk.cncf.io [single-source requirement]: #single-source-requirement [website guidelines]: ../website-guidelines-checklist.md @@ -202,19 +225,20 @@ Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. -* Is the website usable from mobile? -* Are doc pages readable? -* Are all / most website features accessible from mobile -- such as the top-nav, +- Is the website usable from mobile? +- Are doc pages readable? +- Are all / most website features accessible from mobile -- such as the top-nav, site search and in-page table of contents? -* Might a [mobile-first] design make sense for your project? +- Might a [mobile-first] design make sense for your project? -[mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first +[mobile-first]: + https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first Plan for suitable [accessibility][] measures for your website. For example: -* Are color contrasts significant enough for color-impaired readers? -* Are most website features usable using a keyboard only? -* Does text-to-speech offer listeners a good experience? +- Are color contrasts significant enough for color-impaired readers? +- Are most website features usable using a keyboard only? +- Does text-to-speech offer listeners a good experience? It is up to each project to set their own guidelines. @@ -227,32 +251,34 @@ this is branding and marketing. We evaluate on the following: -* Is there an easily recognizable brand for the project (logo + color scheme) +- 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 brand used across the website consistently? +- Is the website’s typography clean and well-suited for reading? Examples: -* https://helm.sh/ +- https://helm.sh/ ### Case studies/social proof -One of the best ways to advertise an open source project is to show other organizations using it. +One of the best ways to advertise an open source project is to show other +organizations using it. We evaluate on the following: -* Are there case studies available for the project and are they documented on the website? -* Are there user testimonials available? -* Is there an active project blog? -* Are there community talks for the project and are they present on the website? -* Is there a logo wall of users/participating organizations? +- Are there case studies available for the project and are they documented on + the website? +- Are there user testimonials available? +- Is there an active project blog? +- Are there community talks for the project and are they present on the website? +- Is there a logo wall of users/participating organizations? Examples: -* https://www.fluentd.org/testimonials (user testimonials) -* https://goharbor.io/ (logo wall) -* https://blog.rook.io/ (blog) +- https://www.fluentd.org/testimonials (user testimonials) +- https://goharbor.io/ (logo wall) +- https://blog.rook.io/ (blog) ### SEO, Analytics and site-local search @@ -262,35 +288,36 @@ while optional, can offer your readers a site-focused search results. We evaluate on the following: -* Analytics: +- Analytics: - Is analytics enabled for the production server? - Is analytics disabled for all other deploys? - If your project used Google Analytics, have you migrated to GA4? - Can Page-not-found (404) reports easily be generated from you site analytics? Provide a sample of the site's current top-10 404s. -* Is site indexing supported for the production server, while disabled for +- Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? -* Is local intra-site search available from the website? -* Are the current custodian(s) of the following accounts clearly documented: +- Is local intra-site search available from the website? +- Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) ### Maintenance planning -Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. +Website maintenance is an important part of project success, especially when +project maintainers aren’t web developers. We evaluate on the following: -* Is your website tooling well supported by the community (i.e., Hugo with the +- Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) -* Are you actively cultivating website maintainers from within the community? -* Are site build times reasonable? -* Do site maintainers have adequate permissions? +- Are you actively cultivating website maintainers from within the community? +- Are site build times reasonable? +- Do site maintainers have adequate permissions? Examples: -* http://kubernetes.io +- http://kubernetes.io ### Other -* Is your website accessible via HTTPS? -* Does HTTP access, if any, redirect to HTTPS? +- Is your website accessible via HTTPS? +- Does HTTP access, if any, redirect to HTTPS? diff --git a/docs/analysis/howto.md b/docs/analysis/howto.md index fd34556..70fa619 100644 --- a/docs/analysis/howto.md +++ b/docs/analysis/howto.md @@ -2,110 +2,210 @@ ## Audience -This document is for members of the CNCF TechDocs team, including contractors or consultants, who need to conduct or assist with an analysis of a CNCF open-source project's technical documentation. - +This document is for members of the CNCF TechDocs team, including contractors or +consultants, who need to conduct or assist with an analysis of a CNCF +open-source project's technical documentation. ## Purpose The goals of a CNCF technical documentation analysis are to: -- Examine the current project technical documentation and website against the CNCF's analysis framework, as described in the doc analysis [criteria](./criteria.md). -- Compare the documentation against the current or proposed maturity level for the overall project. -- Recommends a program of key improvements with the largest return on investment. These improvements are documented as *recommendations* in the analysis document and expanded in a companion [implementation plan](./resources/implementation-template.md) and [issues backlog](./resources/umbrella-issue-template.md). - +- Examine the current project technical documentation and website against the + CNCF's analysis framework, as described in the doc analysis + [criteria](./criteria.md). +- Compare the documentation against the current or proposed maturity level for + the overall project. +- Recommends a program of key improvements with the largest return on + investment. These improvements are documented as _recommendations_ in the + analysis document and expanded in a companion + [implementation plan](./resources/implementation-template.md) and + [issues backlog](./resources/umbrella-issue-template.md). ## Doing a Tech Docs Analysis -The tech docs analysis consists of some repository bookkeeping (Prerequisites), then of three overall tasks: - -1. Write the analysis document: Evaluate the existing project documentation with respect to the project maturity level (or proposed maturity level, if the analysis is associated with an upgrade request). Identify gaps with CNCF criteria. Write general recommendations to close the largest and most important gaps. -2. Write the implementation plan: Decompose the recommendations to specific improvement suggestions. These can be additions or revisions to the docs; reorganization; website infrastructure changes; or any other work that will close the gaps. Make suggestions specific (if you propose reorganizing a section, for example, provide an outline) but provide enough information that a contributor could solve the problem differently if they have a different idea (make it clear that your proposed outline is only one possible reorganization, e.g.). +The tech docs analysis consists of some repository bookkeeping (Prerequisites), +then of three overall tasks: + +1. Write the analysis document: Evaluate the existing project documentation with + respect to the project maturity level (or proposed maturity level, if the + analysis is associated with an upgrade request). Identify gaps with CNCF + criteria. Write general recommendations to close the largest and most + important gaps. +2. Write the implementation plan: Decompose the recommendations to specific + improvement suggestions. These can be additions or revisions to the docs; + reorganization; website infrastructure changes; or any other work that will + close the gaps. Make suggestions specific (if you propose reorganizing a + section, for example, provide an outline) but provide enough information that + a contributor could solve the problem differently if they have a different + idea (make it clear that your proposed outline is only one possible + reorganization, e.g.). 3. Write the issue backlog. -Finally, there are follow-up steps including creating GitHub issues and a pull request, and getting approval from project maintainers. +Finally, there are follow-up steps including creating GitHub issues and a pull +request, and getting approval from project maintainers. ### Prerequisites -This process assumes you have some familiarity with GitHub repositories and pull requests (PRs). +This process assumes you have some familiarity with GitHub repositories and pull +requests (PRs). 1. Clone the [CNCF tech docs repository](https://github.com/cncf/techdocs). 1. Create a branch for the analysis. -1. In the new branch, create a directory for the analysis in the CNCF tech docs /analysis directory. Name the directory `00NN-_PROJECT_`, where *NN* is the next index available in the directory (check for PRs as well, if someone else is working on tech doc analyses), and where _PROJECT_ is a short but not abbreviated project name. For example, for Kubernetes _PROJECT_ would be *kubernetes*, not *k8s*. -1. Copy and rename the analysis doc templates from the `/analysis/analysis-tools` directory as follows: `analysis-template.md` > `_PROJECT_-analysis.md`; `implementation-template.md` > `_PROJECT_-implementation.md`; and `umbrella-issue-template.md` > `_PROJECT_-issues.md`. - +1. In the new branch, create a directory for the analysis in the CNCF tech docs + /analysis directory. Name the directory `00NN-_PROJECT_`, where _NN_ is the + next index available in the directory (check for PRs as well, if someone else + is working on tech doc analyses), and where _PROJECT_ is a short but not + abbreviated project name. For example, for Kubernetes _PROJECT_ would be + _kubernetes_, not _k8s_. +1. Copy and rename the analysis doc templates from the + `/analysis/analysis-tools` directory as follows: `analysis-template.md` > + `_PROJECT_-analysis.md`; `implementation-template.md` > + `_PROJECT_-implementation.md`; and `umbrella-issue-template.md` > + `_PROJECT_-issues.md`. ### Writing the Analysis document -Edit `_PROJECT_-analysis.md` and follow these steps to complete the first step, the analysis: - -1. Define the scope of the analysis. Edit "Scope of analysis" to reflect URLs and repositories included and excluded from the analysis. -1. Review the in-scope URLs and repositories for compliance with the rubric criteria. Note any gaps, as well as any areas that exceed criteria or are exceptionally well executed. I find it easiest to do this separately for each of the three areas of concern (project doc, contributor doc, website), making a pass through the documentation once for each section (Information architecture, New user content, Content maintainability, etc.). Don't worry about a numerical score during this step; instead, note how the documentation complies, or not, with each criterion with respect to the project maturity level (or proposed maturity level, if the analysis is part of a petition for upgrade). Write comments to note the most important gaps and best-executed features of the documentation. -1. Assign ratings to each criterion based on your comments and compliance with the maturity level expectations in the rubric. The ratings are self-explanatory. Keep in mind that "needs improvement" or "meets standards" is with respect to the current (or proposed) maturity level. -1. Write recommendations. The template implies that you'll do this for every criterion; the "Recommendations" headings mirror the "Comments" headings. However, if some alternative framework makes more sense, use that. For example, it might be that two or three of the product documentation criteria are improved by reorganizing the documentation. In this case, rather than repeat the recommendation to reorganize in each section, write a single recommendation and explain how it improves all the areas. This is the first step in moving from the analysis to specific, actionable, time-bound backlog items. +Edit `_PROJECT_-analysis.md` and follow these steps to complete the first step, +the analysis: + +1. Define the scope of the analysis. Edit "Scope of analysis" to reflect URLs + and repositories included and excluded from the analysis. +1. Review the in-scope URLs and repositories for compliance with the rubric + criteria. Note any gaps, as well as any areas that exceed criteria or are + exceptionally well executed. I find it easiest to do this separately for each + of the three areas of concern (project doc, contributor doc, website), making + a pass through the documentation once for each section (Information + architecture, New user content, Content maintainability, etc.). Don't worry + about a numerical score during this step; instead, note how the documentation + complies, or not, with each criterion with respect to the project maturity + level (or proposed maturity level, if the analysis is part of a petition for + upgrade). Write comments to note the most important gaps and best-executed + features of the documentation. +1. Assign ratings to each criterion based on your comments and compliance with + the maturity level expectations in the rubric. The ratings are + self-explanatory. Keep in mind that "needs improvement" or "meets standards" + is with respect to the current (or proposed) maturity level. +1. Write recommendations. The template implies that you'll do this for every + criterion; the "Recommendations" headings mirror the "Comments" headings. + However, if some alternative framework makes more sense, use that. For + example, it might be that two or three of the product documentation criteria + are improved by reorganizing the documentation. In this case, rather than + repeat the recommendation to reorganize in each section, write a single + recommendation and explain how it improves all the areas. This is the first + step in moving from the analysis to specific, actionable, time-bound backlog + items. #### General tips Things to keep in mind while doing the analysis: + - Look for: - - Quick wins – low-effort changes that would have a major impact. - - Large, systemic issues that you can organize a number of issues around. - - The two or three most important issues that impede documentation effectiveness. - - Anything the project does exceptionally well. We can call these out as examples in other evaluations! -- Don't get bogged down in detail when writing comments. Include enough detail that you can describe how to implement a suggested solution. A sentence or two is sufficient for most issues. -- Keep in mind the overall goal of the technical documentation: to make its users more effective. Focus on issues that get in the way of that goal. -- It is not necessary to come up with a recommendation in every case, especially for elements that are satisfactory or if a recommendation would result in minimal improvement. -- Don't worry about grammar and style if they don't affect documentation effectiveness. If writing style impedes understanding, make a note; otherwise move on. An exception: Insist that tasks and procedures be written as clear, step-by-step instructions. -- Some of the criteria, especially around contributor documentation, project governance, and website infrastructure, are essentially check-boxes. These you can quickly investigate, note, and move on. Spend more time analyzing the effectiveness of the project documentation. + - Quick wins – low-effort changes that would have a major impact. + - Large, systemic issues that you can organize a number of issues around. + - The two or three most important issues that impede documentation + effectiveness. + - Anything the project does exceptionally well. We can call these out as + examples in other evaluations! +- Don't get bogged down in detail when writing comments. Include enough detail + that you can describe how to implement a suggested solution. A sentence or two + is sufficient for most issues. +- Keep in mind the overall goal of the technical documentation: to make its + users more effective. Focus on issues that get in the way of that goal. +- It is not necessary to come up with a recommendation in every case, especially + for elements that are satisfactory or if a recommendation would result in + minimal improvement. +- Don't worry about grammar and style if they don't affect documentation + effectiveness. If writing style impedes understanding, make a note; otherwise + move on. An exception: Insist that tasks and procedures be written as clear, + step-by-step instructions. +- Some of the criteria, especially around contributor documentation, project + governance, and website infrastructure, are essentially check-boxes. These you + can quickly investigate, note, and move on. Spend more time analyzing the + effectiveness of the project documentation. #### Common issues -Many common issues seem to come about because open-source software documentation is written by software developers while they are writing the software. This results in documentation that: +Many common issues seem to come about because open-source software documentation +is written by software developers while they are writing the software. This +results in documentation that: + 1. Is organized around features, not users and use cases. -2. Explains technical concepts well, including architecture and design decisions. -3. Contains complete reference information for APIs, CLIs, and configuration parameters. -4. Has missing or incomplete user-oriented "how-to" explanations and operational procedures. +2. Explains technical concepts well, including architecture and design + decisions. +3. Contains complete reference information for APIs, CLIs, and configuration + parameters. +4. Has missing or incomplete user-oriented "how-to" explanations and operational + procedures. + +You may or may not find the following issues in your analysis, but it's worth +keeping them in mind: -You may or may not find the following issues in your analysis, but it's worth keeping them in mind: - Ambiguity around user roles. - Missing or unclear task-based documentation. - Assumptions about the reader's level of knowledge. -- Organization that buries or scatters important information, especially tasks and procedures. +- Organization that buries or scatters important information, especially tasks + and procedures. - Missing or unclear new-user workflows. ### Writing the implementation plan Write the implementation plan. Edit the `_PROJECT_-implementation.md` file. -The gist of the implementation plan is to break down the recommendations in the analysis document. This is an intermediate stage between general recommendations and the issues backlog. For small projects and where the recommendations are independent and time-bound, an implementation plan might not be necessary and you can move straight to writing the backlog. +The gist of the implementation plan is to break down the recommendations in the +analysis document. This is an intermediate stage between general recommendations +and the issues backlog. For small projects and where the recommendations are +independent and time-bound, an implementation plan might not be necessary and +you can move straight to writing the backlog. -If you do write an implementation plan, start with recommendations in the analysis document. Rewrite the recommendations, making them more specific, with a suggested (but not mandatory) implementation. For example, if you recommend reorganizing the documentation, provide a suggested outline, along with an explanation of the reason for the reorg. +If you do write an implementation plan, start with recommendations in the +analysis document. Rewrite the recommendations, making them more specific, with +a suggested (but not mandatory) implementation. For example, if you recommend +reorganizing the documentation, provide a suggested outline, along with an +explanation of the reason for the reorg. ### Writing an issues backlog Write an issues backlog. Edit `_PROJECT_-issues.md`. -The goal of writing an issues backlog is to offer project contributors the opportunity to make the recommended changes. +The goal of writing an issues backlog is to offer project contributors the +opportunity to make the recommended changes. + +Rewrite each action in the implementation plan. If possible, break large actions +into smaller issues. Each issue should be: -Rewrite each action in the implementation plan. If possible, break large actions into smaller issues. Each issue should be: -- Independent. As much as possible, no issue should have another issue as a prerequisite. A contributor should be able to choose an issue, resolve it, and close it without reference to any other issue. -- Time-bound. A contributor should be able to complete an issue in a reasonably short time, say a few hours or a couple of days at most. +- Independent. As much as possible, no issue should have another issue as a + prerequisite. A contributor should be able to choose an issue, resolve it, and + close it without reference to any other issue. +- Time-bound. A contributor should be able to complete an issue in a reasonably + short time, say a few hours or a couple of days at most. -Make the suggested solution even more specific. At this point, the issue should almost be a recipe for making the doc improvement, with the caveat that a contributor is not required to implement the solution as suggested in the issue. +Make the suggested solution even more specific. At this point, the issue should +almost be a recipe for making the doc improvement, with the caveat that a +contributor is not required to implement the solution as suggested in the issue. ## Next Steps ### Including supporting documentation -If you have supporting material that might be helpful to a contributor working on the documentation issues, include them in the directory with the other documents. For example, you might inventory the existing tech doc pages in a spreadsheet; in this case, include a CSV file of the inventory. +If you have supporting material that might be helpful to a contributor working +on the documentation issues, include them in the directory with the other +documents. For example, you might inventory the existing tech doc pages in a +spreadsheet; in this case, include a CSV file of the inventory. ### Creating a pull request -If you have not created a pull request with the analysis documents, do so now. Tag project maintainers and CNCF documentation staff, and ask for comments. +If you have not created a pull request with the analysis documents, do so now. +Tag project maintainers and CNCF documentation staff, and ask for comments. ### Getting contributor feedback -If you haven't met with the project's maintainers yet, do so before you create the issues in GitHub. Ideally you'd like to have a Zoom meeting with any interested parties to get feedback on the analysis and implementation plan. +If you haven't met with the project's maintainers yet, do so before you create +the issues in GitHub. Ideally you'd like to have a Zoom meeting with any +interested parties to get feedback on the analysis and implementation plan. ### Creating GitHub issues -Enter the backlog issues from the issues document into the project documentation GitHub repository using the format in the umbrella-issues-template.md and issues-template.md files. Create one GitHub issue per backlog issue, and create an umbrella issue that contains a checklist item for each issue. +Enter the backlog issues from the issues document into the project documentation +GitHub repository using the format in the umbrella-issues-template.md and +issues-template.md files. Create one GitHub issue per backlog issue, and create +an umbrella issue that contains a checklist item for each issue. diff --git a/docs/analysis/resources/README.md b/docs/analysis/resources/README.md index 6d1e728..d39d6fd 100644 --- a/docs/analysis/resources/README.md +++ b/docs/analysis/resources/README.md @@ -1,15 +1,21 @@ # TechDoc Analysis Templates -This directory contains templates for analyzing a CNCF project's documentation. +This directory contains templates for analyzing a CNCF project's documentation. ## Contents -Use the templates in this directory to perform a documentation analysis for CNCF. These materials provide: -- A relatively objective set of criteria (a "rubric") for evaluating existing documentation and website content, infrastructure, and support. -- An attempt to make the documentation analysis appropriate to the current (or proposed) maturity level for the overall project. -- Emphasis on effective documentation that serves all users associated with the project. +Use the templates in this directory to perform a documentation analysis for +CNCF. These materials provide: -Resources for completing a documentation analysis, including a [how-to][] guide and analysis [criteria][], are in the `docs` directory. +- A relatively objective set of criteria (a "rubric") for evaluating existing + documentation and website content, infrastructure, and support. +- An attempt to make the documentation analysis appropriate to the current (or + proposed) maturity level for the overall project. +- Emphasis on effective documentation that serves all users associated with the + project. + +Resources for completing a documentation analysis, including a [how-to][] guide +and analysis [criteria][], are in the `docs` directory. [how-to]: ../howto.md -[criteria]: ../criteria.md \ No newline at end of file +[criteria]: ../criteria.md diff --git a/docs/analysis/resources/analysis-template.md b/docs/analysis/resources/analysis-template.md index f4eb661..7108821 100644 --- a/docs/analysis/resources/analysis-template.md +++ b/docs/analysis/resources/analysis-template.md @@ -21,13 +21,25 @@ See howto.md for a discussion of the analysis procedure. # Introduction -This document analyzes the effectiveness and completeness of the [_PROJECT_][project-website] 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 +[_PROJECT_][project-website] 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. +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 was written to analyze the current state of _PROJECT_ documentation. It aims to provide project leaders with an informed understanding of potential problems in current project documentation. A second document, `_PROJECT_-impementation.md`, outlines an actionable plan for improvement. A third document, `_PROJECT_-issues.md`, enumerates a backlog of issues to be added to the project documentation repository. These issues can be taken up by contributors to improve the documentation. +This document was written to analyze the current state of _PROJECT_ +documentation. It aims to provide project leaders with an informed understanding +of potential problems in current project documentation. A second document, +`_PROJECT_-impementation.md`, outlines an actionable plan for improvement. A +third document, `_PROJECT_-issues.md`, enumerates a backlog of issues to be +added to the project documentation repository. These issues can be taken up by +contributors to improve the documentation. This document: @@ -37,62 +49,99 @@ This document: ## Scope of analysis -The documentation discussed here includes the entire contents of the website, the technical documentation, and documentation for contributors and users on the _PROJECT_ GitHub repository. +The documentation discussed here includes the entire contents of the website, +the technical documentation, and documentation for contributors and users on the +_PROJECT_ GitHub repository. -The _PROJECT_ website and documentation are written in [Markdown, ReStructured Text, other] and are compiled using the [Hugo, Docusaurus, Sphynx, other] static site generator with the [Docsy, other] theme and served from [the Netlify platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. +The _PROJECT_ website and documentation are written in [Markdown, ReStructured +Text, other] and are compiled using the [Hugo, Docusaurus, Sphynx, other] static +site generator with the [Docsy, other] theme and served from [the Netlify +platform, other]. The site's code is stored on the _PROJECT_ GitHub repo. **In scope:** + - Website: _PROJECT-WEBSITE_ - Documentation: _PROJECT-DOC-URL_ - Website repo: _PROJECT-DOC-REPO_ -- _[Other; might include a demo server, governance site, or other relevant repositories]_ +- _[Other; might include a demo server, governance site, or other relevant + repositories]_ **Out of scope:** -- Other _PROJECT_ repos: _[In general, do not include sub-projects or related "ecosystem" projects]_ +- Other _PROJECT_ repos: _[In general, do not include sub-projects or related + "ecosystem" projects]_ ## How this document is organized -This document is divided into three sections that represent three major areas of concern: +This document is divided into three sections that represent three major areas of +concern: -- **Project documentation:** concerns documentation for users of the _PROJECT_ software, aimed at people who intend to use the project software -- **Contributor documentation:** concerns documentation for new and existing contributors to the _PROJECT_ OSS project -- **Website:** concerns the mechanics of publishing the documentation, and includes branding, website structure, and maintainability +- **Project documentation:** concerns documentation for users of the _PROJECT_ + software, aimed at people who intend to use the project software +- **Contributor documentation:** concerns documentation for new and existing + contributors to the _PROJECT_ OSS project +- **Website:** concerns the mechanics of publishing the documentation, and + includes branding, website structure, and maintainability -Each section begins with summary ratings based on a rubric with appropriate [criteria][criteria-doc] for the section, then proceeds to: -- **Comments**: observations about the existing documentation, with a focus on how it does or does not help _PROJECT_ users achieve their goals. -- **Recommendations**: suggested changes that would improve the effectiveness of the documentation. +Each section begins with summary ratings based on a rubric with appropriate +[criteria][criteria-doc] for the section, then proceeds to: -An accompanying document, [`_PROJECT_-implementation.md`][implementation-doc], 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-doc] and entered as GitHub [issues][project-doc-website]/issues. +- **Comments**: observations about the existing documentation, with a focus on + how it does or does not help _PROJECT_ users achieve their goals. +- **Recommendations**: suggested changes that would improve the effectiveness of + the documentation. +An accompanying document, [`_PROJECT_-implementation.md`][implementation-doc], +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-doc] and +entered as GitHub [issues][project-doc-website]/issues. ## How to use this document -Readers interested only in actionable improvements should skip this document and read the [implementation plan][implementation-doc] and [issues list][issues-doc]. +Readers interested only in actionable improvements should skip this document and +read the [implementation plan][implementation-doc] and [issues +list][issues-doc]. -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: +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-heading] - [Contributor documentation][contributor-heading] - [Website and documentation infrastructure][website-heading] -Examples of CNCF documentation that demonstrate the analysis criteria are linked from the [criteria][criteria-doc] specification. - +Examples of CNCF documentation that demonstrate the analysis criteria are linked +from the [criteria][criteria-doc] specification. ### 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. - +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 -_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [*very high*][criteria-doc] standards for documentation. + +_PROJECT_ is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria-doc] standards for documentation. + -_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. + +_PROJECT_ is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria-doc] professional-quality documentation +alongside the project code. | Criterion | Rating (1-5) | -|----------------------------|----------------| +| -------------------------- | -------------- | | Information architecture | (rating value) | | New user content | (rating value) | | Content maintainability | (rating value) | @@ -113,58 +162,68 @@ _PROJECT_ is an **incubating** project of CNCF. This means that the project shou Make any overall comments about the Project Documentation here. --> -The following sections contain brief assessments of each element of the Project Documentation rubric. +The following sections contain brief assessments of each element of the Project +Documentation rubric. ### Information architecture -The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following: - -* Is there high level conceptual/“About” content? -Is the documentation feature complete? (i.e., each product feature is documented) -* Are there step-by-step instructions (tasks, tutorials) documented for features? -* Are there any key features which are documented but missing task documentation? -* Is the “happy path”/most common use case documented? -Does task and tutorial content demonstrate atomicity and isolation of concerns? (Are tasks clearly named according to user goals?) -* If the documentation does not suffice, is there a clear escalation path for users needing more help? (FAQ, Troubleshooting) -* If the product exposes an API, is there a complete reference? -* Is content up to date and accurate? +The overall structure (pages/subpages/sections/subsections) of your project +documentation. We evaluate on the following: + +- Is there high level conceptual/“About” content? Is the documentation feature + complete? (i.e., each product feature is documented) +- Are there step-by-step instructions (tasks, tutorials) documented for + features? +- Are there any key features which are documented but missing task + documentation? +- Is the “happy path”/most common use case documented? Does task and tutorial + content demonstrate atomicity and isolation of concerns? (Are tasks clearly + named according to user goals?) +- If the documentation does not suffice, is there a clear escalation path for + users needing more help? (FAQ, Troubleshooting) +- If the product exposes an API, is there a complete reference? +- Is content up to date and accurate? ### New user content -New users are the most avid users of documentation, and need content specifically for them. We evaluate on the following: - -* Is “getting started” clearly labeled? (“Getting started”, “Installation”, “First steps”, etc.) -* Is installation documented step-by-step? -* If needed, are multiple OSes documented? -* Do users know where to go after reading the getting started guide? -* Is your new user content clearly signposted on your site’s homepage or at the top of your information architecture? -* Is there easily copy-pastable sample code or other example content? +New users are the most avid users of documentation, and need content +specifically for them. We evaluate on the following: +- Is “getting started” clearly labeled? (“Getting started”, “Installation”, + “First steps”, etc.) +- Is installation documented step-by-step? +- If needed, are multiple OSes documented? +- Do users know where to go after reading the getting started guide? +- Is your new user content clearly signposted on your site’s homepage or at the + top of your information architecture? +- Is there easily copy-pastable sample code or other example content? ### Content maintainability & site mechanics -As a project scales, concerns like localized (translated) content and versioning become large maintenance burdens, particularly if you don’t plan for them. +As a project scales, concerns like localized (translated) content and versioning +become large maintenance burdens, particularly if you don’t plan for them. We evaluate on the following: -* Is your documentation searchable? -* Are you planning for localization/internationalization with regards to site directory structure? Is a localization framework present? -* Do you have a clearly documented method for versioning your content? - +- Is your documentation searchable? +- Are you planning for localization/internationalization with regards to site + directory structure? Is a localization framework present? +- Do you have a clearly documented method for versioning your content? ### Content creation processes -Documentation is only as useful as it is accurate and well-maintained, and requires the same kind of review and approval processes as code. +Documentation is only as useful as it is accurate and well-maintained, and +requires the same kind of review and approval processes as code. We evaluate on the following: -* Is there a clearly documented (ongoing) contribution process for documentation? -* Does your code release process account for documentation creation & updates? -* Who reviews and approves documentation pull requests? -* Does the website have a clear owner/maintainer? - +- Is there a clearly documented (ongoing) contribution process for + documentation? +- Does your code release process account for documentation creation & updates? +- Who reviews and approves documentation pull requests? +- Does the website have a clear owner/maintainer? ### Inclusive language @@ -172,9 +231,10 @@ Creating inclusive project communities is a key goal for all CNCF projects. We evaluate on the following: -* Are there any customer-facing utilities, endpoints, class names, or feature names that use non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website? -* Does the project use language like "simple", "easy", etc.? - +- Are there any customer-facing utilities, endpoints, class names, or feature + names that use non-recommended words as documented by the + [Inclusive Naming Initiative](https://inclusivenaming.org) website? +- Does the project use language like "simple", "easy", etc.? ## Recommendations @@ -190,20 +250,25 @@ We evaluate on the following: ### Inclusive language - # Contributor documentation -_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [*very high*][criteria-doc] standards for documentation. + +_PROJECT_ is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria-doc] standards for documentation. + -_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. + +_PROJECT_ is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria-doc] professional-quality documentation +alongside the project code. | Criterion | Rating (1-5) | -|-------------------------------------------|----------------| -| Communication methods documented | (rating value) | +| ----------------------------------------- | -------------- | +| Communication methods documented | (rating value) | | Beginner friendly issue backlog | (rating value) | -| “New contributor” getting started content | (rating value) | -| Project governance documentation | (rating value) | +| “New contributor” getting started content | (rating value) | +| Project governance documentation | (rating value) | - ## Comments -The following sections contain brief assessments of each element of the Contributor Documentation rubric. +The following sections contain brief assessments of each element of the +Contributor Documentation rubric. ### Communication methods documented -One of the easiest ways to attract new contributors is making sure they know how to reach you. +One of the easiest ways to attract new contributors is making sure they know how +to reach you. We evaluate on the following: -* Is there a Slack/Discord/Discourse/etc. community and is it prominently linked from your website? -* Is there a direct link to your GitHub organization/repository? -* Are weekly/monthly project meetings documented? Is it clear how someone can join those meetings? -* Are mailing lists documented? +- Is there a Slack/Discord/Discourse/etc. community and is it prominently linked + from your website? +- Is there a direct link to your GitHub organization/repository? +- Are weekly/monthly project meetings documented? Is it clear how someone can + join those meetings? +- Are mailing lists documented? ### Beginner friendly issue backlog We evaluate on the following: -* Are docs issues well-triaged? -* Is there a clearly marked way for new contributors to make code or documentation contributions (i.e. a “good first issue” label)? -* Are issues well-documented (i.e., more than just a title)? -* Are issues maintained for staleness? +- Are docs issues well-triaged? +- Is there a clearly marked way for new contributors to make code or + documentation contributions (i.e. a “good first issue” label)? +- Are issues well-documented (i.e., more than just a title)? +- Are issues maintained for staleness? ### New contributor getting started content -Open source is complex and projects have many processes to manage that. Are processes easy to understand and written down so that new contributors can jump in easily? +Open source is complex and projects have many processes to manage that. Are +processes easy to understand and written down so that new contributors can jump +in easily? We evaluate on the following: -* 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? +- 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 @@ -260,7 +331,7 @@ One of the CNCF’s core project values is open governance. We evaluate on the following: -* Is project governance clearly documented? +- Is project governance clearly documented? ## Recommendations @@ -274,16 +345,21 @@ We evaluate on the following: ### Project governance documentation - # Website and infrastructure -_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [*very high*][criteria-doc] standards for documentation. + +_PROJECT_ is a **graduated** project of CNCF. This means that the project should +have [_very high_][criteria-doc] standards for documentation. + -_PROJECT_ is an **incubating** project of CNCF. This means that the project should be [*developing*][criteria-doc] professional-quality documentation alongside the project code. -| Criterion | Rating (1-5) | -|---------------------------------------------|----------------| +_PROJECT_ is an **incubating** project of CNCF. This means that the project +should be [_developing_][criteria-doc] professional-quality documentation +alongside the project code. + +| Criterion | Rating (1-5) | +| ------------------------------------------- | -------------- | | Single-source for all files | (rating value) | | Meets min website req. (for maturity level) | (rating value) | | Usability, accessibility, and design | (rating value) | @@ -307,22 +383,22 @@ _PROJECT_ is an **incubating** project of CNCF. This means that the project shou 5 - exemplary --> - ## Comments -The following sections contain brief assessments of each element of the Website and documentation infrastructure rubric. +The following sections contain brief assessments of each element of the Website +and documentation infrastructure rubric. - ### Single-source requirement -Source files for _all website pages_ should reside in a single repo. -Among other problems, keeping source files in two places: +Source files for _all website pages_ should reside in a single repo. Among other +problems, keeping source files in two places: + - confuses contributors - requires you to keep two sources in sync - increases the likelihood of errors @@ -337,10 +413,12 @@ documented strategy for managing mirrored files and new contributions. ### Minimal website requirements -Listed here are the minimal website requirements for projects based on their [maturity level][maturity-level], either incubating or graduated. (These are the only two levels for which a tech docs analysis can be requested.) +Listed here are the minimal website requirements for projects based on their +[maturity level][maturity-level], either incubating or graduated. (These are the +only two levels for which a tech docs analysis can be requested.) | Criterion | Incubating Requirement | Graduated Requirement | -|------------------------------------------|---------------------------------------------------------|-------------------------------------------| +| ---------------------------------------- | ------------------------------------------------------- | ----------------------------------------- | | [Website guidelines][website-guidelines] | All guidelines satisfied | All guidelines satisfied | | [Docs analysis][analysis-doc] (this) | Requested through CNCF [service desk][cncf-servicedesk] | All follow-up actions addressed | | **Project doc**: stakeholders | Roles identified and doc needs documented | All stakeholder need identified | @@ -349,26 +427,30 @@ Listed here are the minimal website requirements for projects based on their [ma [git-submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules [website-guidelines]: ../../website-guidelines-checklist.md -[maturity-level]: https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations +[maturity-level]: + https://github.com/cncf/toc/tree/main/process#ii-stages---definitions--expectations [cncf-servicedesk]: https://servicedesk.cncf.io ### Usability, accessibility and devices -Most CNCF websites are accessed from mobile and other non-desktop devices at least 10-20% of the time. Planning for this early in your website's design will be much less effort than retrofitting a desktop-first design. +Most CNCF websites are accessed from mobile and other non-desktop devices at +least 10-20% of the time. Planning for this early in your website's design will +be much less effort than retrofitting a desktop-first design. -* Is the website usable from mobile? -* Are doc pages readable? -* Are all / most website features accessible from mobile -- such as the top-nav, +- Is the website usable from mobile? +- Are doc pages readable? +- Are all / most website features accessible from mobile -- such as the top-nav, site search and in-page table of contents? -* Might a [mobile-first] design make sense for your project? +- Might a [mobile-first] design make sense for your project? -[mobile-first]: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first +[mobile-first]: + https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/Mobile_first Plan for suitable [accessibility][] measures for your website. For example: -* Are color contrasts significant enough for color-impaired readers? -* Are most website features usable using a keyboard only? -* Does text-to-speech offer listeners a good experience? +- Are color contrasts significant enough for color-impaired readers? +- Are most website features usable using a keyboard only? +- Does text-to-speech offer listeners a good experience? It is up to each project to set their own guidelines. @@ -381,23 +463,24 @@ this is branding and marketing. We evaluate on the following: -* Is there an easily recognizable brand for the project (logo + color scheme) +- 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 brand used across the website consistently? +- Is the website’s typography clean and well-suited for reading? ### Case studies/social proof -One of the best ways to advertise an open source project is to show other organizations using it. +One of the best ways to advertise an open source project is to show other +organizations using it. We evaluate on the following: -* Are there case studies available for the project and are they documented on the website? -* Are there user testimonials available? -* Is there an active project blog? -* Are there community talks for the project and are they present on the website? -* Is there a logo wall of users/participating organizations? - +- Are there case studies available for the project and are they documented on + the website? +- Are there user testimonials available? +- Is there an active project blog? +- Are there community talks for the project and are they present on the website? +- Is there a logo wall of users/participating organizations? ### SEO, Analytics and site-local search @@ -407,35 +490,35 @@ while optional, can offer your readers a site-focused search results. We evaluate on the following: -* Analytics: +- Analytics: - Is analytics enabled for the production server? - Is analytics disabled for all other deploys? - If your project used Google Analytics, have you migrated to GA4? - Can Page-not-found (404) reports easily be generated from you site analytics? Provide a sample of the site's current top-10 404s. -* Is site indexing supported for the production server, while disabled for +- Is site indexing supported for the production server, while disabled for website previews and builds for non-default branches? -* Is local intra-site search available from the website? -* Are the current custodian(s) of the following accounts clearly documented: +- Is local intra-site search available from the website? +- Are the current custodian(s) of the following accounts clearly documented: analytics, Google Search Console, site-search (such as Google CSE or Algolia) - ### Maintenance planning -Website maintenance is an important part of project success, especially when project maintainers aren’t web developers. +Website maintenance is an important part of project success, especially when +project maintainers aren’t web developers. We evaluate on the following: -* Is your website tooling well supported by the community (i.e., Hugo with the +- Is your website tooling well supported by the community (i.e., Hugo with the Docsy theme) or commonly used by CNCF projects (our recommended tech stack?) -* Are you actively cultivating website maintainers from within the community? -* Are site build times reasonable? -* Do site maintainers have adequate permissions? +- Are you actively cultivating website maintainers from within the community? +- Are site build times reasonable? +- Do site maintainers have adequate permissions? ### Other -* Is your website accessible via HTTPS? -* Does HTTP access, if any, redirect to HTTPS? +- Is your website accessible via HTTPS? +- Does HTTP access, if any, redirect to HTTPS? ## Recommendations @@ -457,7 +540,6 @@ We evaluate on the following: ### Other - [project-website]: _PROJECT-WEBSITE_ @@ -473,4 +555,3 @@ We evaluate on the following: [website-heading]: #website [rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 [website-guidelines]: ../../website-guidelines-checklist.md - diff --git a/docs/analysis/resources/implementation-template.md b/docs/analysis/resources/implementation-template.md index d73f4d9..a32927e 100644 --- a/docs/analysis/resources/implementation-template.md +++ b/docs/analysis/resources/implementation-template.md @@ -5,13 +5,24 @@ tags: _PROJECT_ # Introduction -This document provides actionable suggestions for improving the _PROJECT_ technical documentation. +This document provides actionable suggestions for improving the _PROJECT_ +technical documentation. -For an analysis and general discussion of recommendations on _PROJECT_ technical documentation, see [_PROJECT_-analysis.md][]. +For an analysis and general discussion of recommendations on _PROJECT_ technical +documentation, see [_PROJECT_-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. +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: @@ -29,7 +40,6 @@ The top-level documentation recommendations for this project are: ## Issue 2 - [rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/docs/analysis/resources/issue-template.md b/docs/analysis/resources/issue-template.md index 6b8a071..e12af81 100644 --- a/docs/analysis/resources/issue-template.md +++ b/docs/analysis/resources/issue-template.md @@ -11,19 +11,24 @@ tags: _PROJECT_ Audience: -Type: +Type: + + # Context - + -This issue tracks recommended changes resulting from an analysis of the etcd documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/ +This issue tracks recommended changes resulting from an analysis of the etcd +documentation commissioned by CNCF. The analysis and supporting documents are +here: https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/ # Possible Implementation Related material in the current doc: + - https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials @@ -34,7 +39,8 @@ Use the following outline to write a procedure for each task: - Prerequisites (bullet list of prerequisite conditions, if any) - Procedure - 1. Step 1 (keep steps discrete and atomic. Put command-line input and expected output in a code block.) - 2. Step 2 ... -- Result (optional; describe output or side effects if they're notable or unexpected.) - + 1. Step 1 (keep steps discrete and atomic. Put command-line input and expected + output in a code block.) + 2. Step 2 ... +- Result (optional; describe output or side effects if they're notable or + unexpected.) diff --git a/docs/analysis/resources/umbrella-issue-template.md b/docs/analysis/resources/umbrella-issue-template.md index 27e2006..f834846 100644 --- a/docs/analysis/resources/umbrella-issue-template.md +++ b/docs/analysis/resources/umbrella-issue-template.md @@ -11,14 +11,18 @@ tags: _PROJECT_ -This issue tracks recommended changes resulting from an analysis of the _PROJECT_ documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/ +This issue tracks recommended changes resulting from an analysis of the +_PROJECT_ documentation commissioned by CNCF. The analysis and supporting +documents are here: +https://github.com/cncf/techdocs/tree/main/assessments/00NN-project/ The CNCF etcd documentation effort is tracked in the CNCF Tech Docs repo: https://github.com/cncf/techdocs/issues/NNN # Issues -This is a list of issues representing the recommended work on the _PROJECT_ website and technical documentation. +This is a list of issues representing the recommended work on the _PROJECT_ +website and technical documentation. ## Issue: Item 1 diff --git a/docs/analytics.md b/docs/analytics.md index 8cae4c0..89bfdfd 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -79,7 +79,8 @@ Follow these steps: - Select **Admin** (bottom of left-nav) - Select **GA4 Setup Assistant** - - Select **Get started** under **I want to create a new Google Analytics 4 property**. + - Select **Get started** under **I want to create a new Google Analytics 4 + property**. - In the dialog that opens up, check the **Enable data collection using your existing global site tag(s)** checkbox if it is enabled; otherwise carry on. The checkbox will be enabled (selectable) only if your site uses @@ -90,12 +91,11 @@ Follow these steps: measurement ID. Continuing from the previous step: - Select **Go to your GA4 property** from the **GA4 Setup Assistant** view - of your UA property.
- This will open an analytics console onto your GA4 site tag. Perform the - remaining steps from your GA4 console. + of your UA property.
This will open an analytics console onto your GA4 + site tag. Perform the remaining steps from your GA4 console. - Select **Admin** > **Data stream** - Select the (only) data stream to view its details. - - 📋 **Copy the __measurement ID__**, you'll need it later, and paste it + - 📋 **Copy the **measurement ID\*\*\*\*, you'll need it later, and paste it into the appropriate row of the [status table][]. 5. Rename your UA property by adding the `- UA` suffix. From the UA console: @@ -121,7 +121,8 @@ Follow these steps: - Open **Admin** > **Tracking Info** > **Tracking Code**. - Open **Connected Site Tags**. - - In **Enter ID of tag to connect**: enter your GA site tag (the ID starting with `G-`). + - In **Enter ID of tag to connect**: enter your GA site tag (the ID starting + with `G-`). - In **Nickname**, optionally add the name of the domain, for example, `kubernetes.io`. - Click **Connect**. @@ -148,14 +149,14 @@ analytics library. - [Docusaurus][]: - v1: add a `gtag: true` site configuration parameter. - v2: enable the gtag plugin. - - [Docsy][] & Hugo version 0.82.0 or later: your project will automatically be - switched to using the `gtag` library once you complete the next step. + - [Docsy][] & Hugo version 0.82.0 or later: your project will automatically + be switched to using the `gtag` library once you complete the next step. - Hugo 0.82.0 or earlier (with or without use of Docsy): consider adding a `partial` named something like `google-analytics.html` containing the global tag snippet shown in [Add gtag.js to your site][], but using your - GA4 measurement ID. Conditionally include this partial in the `` element - of your website pages, _provided that Hugo is building in a production - environment_. + GA4 measurement ID. Conditionally include this partial in the `` + element of your website pages, _provided that Hugo is building in a + production environment_. 2. Set the GA4 ID as the main GA ID. Again, how you do this will depend on your project's site generator and setup. Here are some guidelines: @@ -182,8 +183,10 @@ project's GA4 measurement ID. Details are provided in [Adding Analytics][]. Of course, this may require you to upgrade the version of [Docsy][] and/or Hugo that your project is using. -[add gtag.js to your site]: https://developers.google.com/analytics/devguides/collection/gtagjs/ -[adding analytics]: https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics +[add gtag.js to your site]: + https://developers.google.com/analytics/devguides/collection/gtagjs/ +[adding analytics]: + https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics [analytics.js]: https://support.google.com/analytics/answer/10268458 [connected]: https://support.google.com/analytics/answer/9973999 [etcd.io issue #595]: https://github.com/etcd-io/website/issues/595 @@ -191,11 +194,14 @@ that your project is using. [docusaurus]: https://docusaurus.io/ [ga4-dev]: https://developers.google.com/analytics/devguides/migration [ga4]: https://support.google.com/analytics/answer/10089681 -[ga4+ua-dev]: https://developers.google.com/analytics/devguides/migration/measurement/add-ga4 +[ga4+ua-dev]: + https://developers.google.com/analytics/devguides/migration/measurement/add-ga4 [gtag.js]: https://support.google.com/analytics/answer/10220869 [issue #108]: https://github.com/cncf/techdocs/issues/108 [migration-help]: https://support.google.com/analytics/answer/10759417 -[opentelemetry.io/layouts/partials/google-analytics.html]: https://github.com/open-telemetry/opentelemetry.io/blob/3d8a59ea508b46497500297f334a079a4f91e293/layouts/partials/google-analytics.html +[opentelemetry.io/layouts/partials/google-analytics.html]: + https://github.com/open-telemetry/opentelemetry.io/blob/3d8a59ea508b46497500297f334a079a4f91e293/layouts/partials/google-analytics.html [stage 2]: #stage-2---configure-the-ga4-id-as-the-main-analytics-id -[status table]: https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA +[status table]: + https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA [ua]: https://support.google.com/analytics/answer/11583528 diff --git a/docs/assistance.md b/docs/assistance.md index d11fe5c..a322e87 100644 --- a/docs/assistance.md +++ b/docs/assistance.md @@ -1,53 +1,100 @@ # 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: - -1. Provide a baseline analysis of the project's documentation quality measured against the project's [maturity level](analysis/criteria.md). Often, projects request an analysis in support of promotion to a new maturity level. -1. Recommend changes that will reduce the gap between the documentation and the maturity of the overall project. +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: + +1. Provide a baseline analysis of the project's documentation quality measured + against the project's [maturity level](analysis/criteria.md). Often, projects + request an analysis in support of promotion to a new maturity level. +1. Recommend changes that will reduce the gap between the documentation and the + maturity of the overall project. 1. Expand on the recommended changes in an implementation plan. -1. Break down the implementation into a documentation project backlog comprising a GitHub Issues list. -1. Support the project team's contributors in taking up and completing the issue backlog items. -1. Leave the project team with an improved understanding and skill base for improving and maintaining the project documentation. +1. Break down the implementation into a documentation project backlog comprising + a GitHub Issues list. +1. Support the project team's contributors in taking up and completing the issue + backlog items. +1. Leave the project team with an improved understanding and skill base for + improving and maintaining the project documentation. ## Phase 0: Training -Some level of familiarity with the technical documentation process is required to: +Some level of familiarity with the technical documentation process is required +to: - Work effectively with technical writers - Draft technical documentation (for non-writers) - Get the best results out of the Assistance Program -For this reason, CNCF offers free training on documentation essentials for project contributors and maintainers. To get the most from the Assistance Program, project contributors are encouraged to do the training *before* engaging a documentation specialist to complete the documentation analysis. +For this reason, CNCF offers free training on documentation essentials for +project contributors and maintainers. To get the most from the Assistance +Program, project contributors are encouraged to do the training _before_ +engaging a documentation specialist to complete the documentation analysis. -The training program consists of the following online courses. Anyone can sign up for and complete the courses at their own pace. +The training program consists of the following online courses. Anyone can sign +up for and complete the courses at their own pace. 1. [Open Source Technical Documentation Essentials (LFC111)](https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/) 1. [Creating Effective Documentation for Developers (LFC112)](https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/) ## Phase 1: Documentation analysis -A technical writer (on CNCF staff or on contract) analyzes the documentation. Based on the standards developed as part of the CNCF TechDocs program, the writer: - -1. Estimates the maturity level of the documentation compared to the current or desired maturity level of the software project using a rubric developed by CNCF. The rubric is divided into three categories: - 1. Project documentation: The end-user documentation for the project's work product, typically (but not always) an application, API, protocol, or some other software product. - 1. Contributor documentation: Documentation about the project, aimed at project contributors and describing procedures, infrastructure, and customs for doing project work. This includes artifacts that define procedures and governance; recruit, orient, and train project contributors; and name responsible parties (project leaders, often generically called *maintainers*). - 1. Website: The technical infrastructure behind the documentation and the project's web presence, including website generation, versioning, SEO, analytics, and security. -1. Collaborates with project leadership to identify user roles and objectives for software users. -1. Proposes changes, if necessary, to the organization and content of the documentation to close gaps with the target maturity level. -1. Writes an implementation plan describing improvements that address the gaps identified by the analysis. +A technical writer (on CNCF staff or on contract) analyzes the documentation. +Based on the standards developed as part of the CNCF TechDocs program, the +writer: + +1. Estimates the maturity level of the documentation compared to the current or + desired maturity level of the software project using a rubric developed by + CNCF. The rubric is divided into three categories: + 1. Project documentation: The end-user documentation for the project's work + product, typically (but not always) an application, API, protocol, or some + other software product. + 1. Contributor documentation: Documentation about the project, aimed at + project contributors and describing procedures, infrastructure, and + customs for doing project work. This includes artifacts that define + procedures and governance; recruit, orient, and train project + contributors; and name responsible parties (project leaders, often + generically called _maintainers_). + 1. Website: The technical infrastructure behind the documentation and the + project's web presence, including website generation, versioning, SEO, + analytics, and security. +1. Collaborates with project leadership to identify user roles and objectives + for software users. +1. Proposes changes, if necessary, to the organization and content of the + documentation to close gaps with the target maturity level. +1. Writes an implementation plan describing improvements that address the gaps + identified by the analysis. ## Phase 2: Backlog creation -Once a high-level improvement plan has been written and approved, the tech writer analyzes the proposed changes to create a backlog of actionable, individual writing assignments and other tasks to improve the documentation. These tasks should have two primary characteristics: -- As much as possible, they should be independent of each other so they can be completed in any order by any combination of contributors; and -- They should be time-constrained. If possible, large tasks should be broken down into smaller, independent tasks that require hours or days rather than weeks to complete. +Once a high-level improvement plan has been written and approved, the tech +writer analyzes the proposed changes to create a backlog of actionable, +individual writing assignments and other tasks to improve the documentation. +These tasks should have two primary characteristics: + +- As much as possible, they should be independent of each other so they can be + completed in any order by any combination of contributors; and +- They should be time-constrained. If possible, large tasks should be broken + down into smaller, independent tasks that require hours or days rather than + weeks to complete. ## Phase 3: Documentation improvement -Community members work on the issues created in the previous phase. Ideally, tech writers are available to advise contributors and edit work, especially if the contributing community members are not trained technical writers. Remember that the training courses in Phase 0 are available to prepare contributors with general knowledge of the process. +Community members work on the issues created in the previous phase. Ideally, +tech writers are available to advise contributors and edit work, especially if +the contributing community members are not trained technical writers. Remember +that the training courses in Phase 0 are available to prepare contributors with +general knowledge of the process. -We know that recruiting contributors to write documentation can be difficult. While this is largely the responsibility of the project leadership, CNCF is actively working on ways to encourage doc contributions. For example, creating a backlog of time-bounded issues is an attempt to lower barriers, both psychological and logistical, to documentation creation and maintenance. +We know that recruiting contributors to write documentation can be difficult. +While this is largely the responsibility of the project leadership, CNCF is +actively working on ways to encourage doc contributions. For example, creating a +backlog of time-bounded issues is an attempt to lower barriers, both +psychological and logistical, to documentation creation and maintenance. ## Phase 4: Impact analysis -Projects are encouraged to collect metrics (using Google analytics and page feedback data) on documentation usage as a means of assessing the effectiveness of documentation improvements. +Projects are encouraged to collect metrics (using Google analytics and page +feedback data) on documentation usage as a means of assessing the effectiveness +of documentation improvements. diff --git a/docs/hugo-and-docsy.md b/docs/hugo-and-docsy.md index 9557b5a..4915534 100644 --- a/docs/hugo-and-docsy.md +++ b/docs/hugo-and-docsy.md @@ -4,5 +4,5 @@ Tips: - [Audit your published site for problems][] - -[Audit your published site for problems]: https://discourse.gohugo.io/t/audit-your-published-site-for-problems/35184 +[Audit your published site for problems]: + https://discourse.gohugo.io/t/audit-your-published-site-for-problems/35184 diff --git a/docs/localization/README.md b/docs/localization/README.md index 74f20a9..aae60c1 100644 --- a/docs/localization/README.md +++ b/docs/localization/README.md @@ -1,10 +1,13 @@ -# CNCF Localization Guides +# CNCF Localization Guides -This directory contains a growing collection of localization guides that CNCF projects can freely use, copy, and adapt. +This directory contains a growing collection of localization guides that CNCF +projects can freely use, copy, and adapt. Every guide here must meet the following requirements: + - Has a permissive open-source license. -- Is original or comes from a specified source that has a permissive open-source license. +- Is original or comes from a specified source that has a permissive open-source + license. - Meets the requirements of the original open-source license. Guides here must not violate copyright or licensing requirements. diff --git a/docs/netlify-domains-setup.md b/docs/netlify-domains-setup.md index f86e969..2150de0 100644 --- a/docs/netlify-domains-setup.md +++ b/docs/netlify-domains-setup.md @@ -1,36 +1,54 @@ -# Netlify and domain setup +# Netlify and domain setup ## Netlify -If a project already has its own Netlify instance, ask them to add @celestehorgan and @caniszczyk as administrators. As a part of their project onboarding, any billing information should be taken care of. If it isn't, ask them to open a [CNCF Service Desk](https://github.com/cncf/servicedesk) ticket. +If a project already has its own Netlify instance, ask them to add +@celestehorgan and @caniszczyk as administrators. As a part of their project +onboarding, any billing information should be taken care of. If it isn't, ask +them to open a [CNCF Service Desk](https://github.com/cncf/servicedesk) ticket. -If a project does not have a website, or is migrating from using GitHub pages to Netlify, create a new site for them under the CNCF Projects netlify instance. +If a project does not have a website, or is migrating from using GitHub pages to +Netlify, create a new site for them under the CNCF Projects netlify instance. ### Netlify maintainers - Ensure that @celestehorgan and @caniszczyk are Owners if they are not already. -- Contact the project and ask for **at least two** maintainers for Netlify. You will need their GitHub usernames. Add them either as Collaborators to specific sites (if in the CNCF Projects Netlify team) or as Collaboators for the Netlify team. +- Contact the project and ask for **at least two** maintainers for Netlify. You + will need their GitHub usernames. Add them either as Collaborators to specific + sites (if in the CNCF Projects Netlify team) or as Collaboators for the + Netlify team. -## Domains +## Domains -If a project has a pre-existing domain, this should be transferred to the CNCF during their onboarding process. +If a project has a pre-existing domain, this should be transferred to the CNCF +during their onboarding process. -If a project is new and does not have a domain name, they should open a [CNCF Service Desk](https://github.com/cncf/servicedesk) ticket to arrange for one. +If a project is new and does not have a domain name, they should open a +[CNCF Service Desk](https://github.com/cncf/servicedesk) ticket to arrange for +one. -In most cases, we prefer to manage domains for project websites using Netlify DNS. +In most cases, we prefer to manage domains for project websites using Netlify +DNS. At the moment, @caniszczyk manages domain transfers. ### Netlify DNS domains -When using Netlify DNS, we delegate the domain from another provider to Netlify DNS. Read [Netlify DNS](https://docs.netlify.com/domains-https/netlify-dns/) for more. +When using Netlify DNS, we delegate the domain from another provider to Netlify +DNS. Read [Netlify DNS](https://docs.netlify.com/domains-https/netlify-dns/) for +more. ### Alias domains and projects with multiple domain names -Some projects have more than one domain name and want all of them to point to their website. In this case, read [Multiple Domains](https://docs.netlify.com/domains-https/custom-domains/multiple-domains/) for more information, and ask them to open a [CNCF Service Desk](https://github.com/cncf/servicedesk) ticket. +Some projects have more than one domain name and want all of them to point to +their website. In this case, read +[Multiple Domains](https://docs.netlify.com/domains-https/custom-domains/multiple-domains/) +for more information, and ask them to open a +[CNCF Service Desk](https://github.com/cncf/servicedesk) ticket. ### Domains that don't point to Netlify websites -Occasionally projects have domain names that don't point to websites. These are used for, among other things, email addresses. +Occasionally projects have domain names that don't point to websites. These are +used for, among other things, email addresses. -Issues related to these should be forwarded on to Linux Foundation IT staff. \ No newline at end of file +Issues related to these should be forwarded on to Linux Foundation IT staff. diff --git a/docs/repo-setup.md b/docs/repo-setup.md index 5128101..d437e58 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -1,53 +1,66 @@ -# Repository setup +# Repository setup -We recommend that CNCF projects separate docs into their own repository, away from code. This has the following advantages: - -- Docs contributors don't need to know the full code build pipeline -- It simplifies repo management/continuous integration setup +We recommend that CNCF projects separate docs into their own repository, away +from code. This has the following advantages: +- Docs contributors don't need to know the full code build pipeline +- It simplifies repo management/continuous integration setup For more information: -- The [`cncf/project-template`](https://github.com/cncf/project-template) repository contains many of the files needed to set up a new repository +- The [`cncf/project-template`](https://github.com/cncf/project-template) + repository contains many of the files needed to set up a new repository ## CLA/DCO CLA/DCO should be set up for a project as a part of their project onboarding. -## License files +## License files -Unless otherwise specified, documentation for CNCF projects is licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Code is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). +Unless otherwise specified, documentation for CNCF projects is licensed under +[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Code is licensed +under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). -Most CNCF documentation repositories are a mix of code (website code) and documentation itself, so they need two license files. +Most CNCF documentation repositories are a mix of code (website code) and +documentation itself, so they need two license files. -For documentation this means you must: +For documentation this means you must: -1. Add copyright notices for both the code and the docs to the repository's `README` and the website's footer +1. Add copyright notices for both the code and the docs to the repository's + `README` and the website's footer -For the repository: +For the repository: ``` # License $PROJECT_NAME is licensed under an [Apache 2.0 license](./LICENSE). -The #PROJECT_NAME documentation is licensed under a [CC-BY-4.0 license](./LICENSE-docs). +The #PROJECT_NAME documentation is licensed under a [CC-BY-4.0 license](./LICENSE-docs). ``` For the footer: -- [`cncf/hugo-netlify-starter`](https://github.com/cncf/hugo-netlify-starter/blob/main/layouts/partials/footer.html) contains a basic implementation, where the year and project name are parameterized. - +- [`cncf/hugo-netlify-starter`](https://github.com/cncf/hugo-netlify-starter/blob/main/layouts/partials/footer.html) + contains a basic implementation, where the year and project name are + parameterized. -2. Add both the CC-BY-4.0 `LICENCE-docs` and Apache 2.0 `LICENCE` files to the root directory of the documentation - - Plain text versions of both [here](https://github.com/cncf/project-template) +2. Add both the CC-BY-4.0 `LICENCE-docs` and Apache 2.0 `LICENCE` files to the + root directory of the documentation + - Plain text versions of both + [here](https://github.com/cncf/project-template) For more information: -- Read [CNCF's project copyright guidelines](https://github.com/cncf/foundation/blob/master/copyright-notices.md) -- And the [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) +- Read + [CNCF's project copyright guidelines](https://github.com/cncf/foundation/blob/master/copyright-notices.md) +- And the + [IP Policy](https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) ## README -All docs repositories should have a README file that includes build instructions. Look at [Longhorn's](https://github.com/longhorn/website) for an example, and the [`cncf/project-template`](https://github.com/cncf/project-template) for boilerplate. - +All docs repositories should have a README file that includes build +instructions. Look at [Longhorn's](https://github.com/longhorn/website) for an +example, and the +[`cncf/project-template`](https://github.com/cncf/project-template) for +boilerplate. diff --git a/docs/searching-documentation.md b/docs/searching-documentation.md index 9591a4c..18e411b 100644 --- a/docs/searching-documentation.md +++ b/docs/searching-documentation.md @@ -1,45 +1,55 @@ # Documentation Search -This page describes some common alternatives for static site search. -* [Google search](#programmable-search-engine-by-google) -* [Docsearch by Algolia](#docsearch-by-algolia) -* [Lunr](#lunr) +This page describes some common alternatives for static site search. +- [Google search](#programmable-search-engine-by-google) +- [Docsearch by Algolia](#docsearch-by-algolia) +- [Lunr](#lunr) ## Programmable Search Engine by Google -[Google’s programmable search engine](https://developers.google.com/custom-search/docs/overview) is a search tool that crawls your **live site** and renders results on your website. +[Google’s programmable search engine](https://developers.google.com/custom-search/docs/overview) +is a search tool that crawls your **live site** and renders results on your +website. ### Pros + - Easy to configure and setup - Multi-language support - Support for image search - Search across a specified collection of sites or pages - No daily limits for queries or records. - ### Cons -- Search index is completely managed and hosted on Google servers. +- Search index is completely managed and hosted on Google servers. ## Docsearch by Algolia -[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the Algolia search engine that crawls your docs and provides a dropdown search experience on your website. + +[DocSearch](https://docsearch.algolia.com/) is a search tool powered by the +Algolia search engine that crawls your docs and provides a dropdown search +experience on your website. ### Pros -- Provides Front-end widgets out of the box: search input, dynamic positioning of search results, etc. + +- Provides Front-end widgets out of the box: search input, dynamic positioning + of search results, etc. - Integrations with popular frameworks - Support for multi-language search. ### Cons + - Not entirely free- Limited to 10k records - Limited access to features. - ## Lunr -[Lunr.js](https://lunrjs.com/) is a small, full-text search library for use in the browser. Lunr enables you to provide a great search experience without needing external, server-side, search services. +[Lunr.js](https://lunrjs.com/) is a small, full-text search library for use in +the browser. Lunr enables you to provide a great search experience without +needing external, server-side, search services. ### Pros + - Support for offline search - No external package dependency - Completely free and open source @@ -47,12 +57,22 @@ This page describes some common alternatives for static site search. - Support for multi-language search - Search index is completely managed and hosted by the owner. - ### Cons -- Can be complex to configure and setup (If a team is already using hugo/docsy, this should be *very* easy to setup). + +- Can be complex to configure and setup (If a team is already using hugo/docsy, + this should be _very_ easy to setup). - Depending on site setup, may require javascript knowledge ## When Is It Best To Use One Over Another? -If you are looking to create a search capability for your open source project without having to depend on a 3rd party service, then you should consider using [Lunr](https://lunrjs.com/). You can take a look at [this custom implementation](https://github.com/vitessio/website/pull/1119) or [Hugo/Docsy implementation](https://github.com/etcd-io/website/pull/403) to see the different ways we used Lunr to implement search. -If you are looking to create a search engine that not only focuses on the contents of one website (site search), but on a particular topic from multiple sites, then you should consider the [Programmable Search Engine (Google search)](https://developers.google.com/custom-search/docs/overview). +If you are looking to create a search capability for your open source project +without having to depend on a 3rd party service, then you should consider using +[Lunr](https://lunrjs.com/). You can take a look at +[this custom implementation](https://github.com/vitessio/website/pull/1119) or +[Hugo/Docsy implementation](https://github.com/etcd-io/website/pull/403) to see +the different ways we used Lunr to implement search. + +If you are looking to create a search engine that not only focuses on the +contents of one website (site search), but on a particular topic from multiple +sites, then you should consider the +[Programmable Search Engine (Google search)](https://developers.google.com/custom-search/docs/overview). diff --git a/docs/services.md b/docs/services.md index 6fced67..d11feff 100644 --- a/docs/services.md +++ b/docs/services.md @@ -1,86 +1,115 @@ # Services for projects -The CNCF provides technical writing and documentation website services for all its projects. +The CNCF provides technical writing and documentation website services for all +its projects. -All requests are subject to approval by the CNCF and should be submitted through the [CNCF service desk](https://servicedesk.cncf.io). +All requests are subject to approval by the CNCF and should be submitted through +the [CNCF service desk](https://servicedesk.cncf.io). ## Docs assessment -**What it is:** A CNCF technical writer looks at your existing documentation, identifies strengths, missing areas, and weaknesses in your existing documentation. They produce a document for project maintainers outlining their findings. +**What it is:** A CNCF technical writer looks at your existing documentation, +identifies strengths, missing areas, and weaknesses in your existing +documentation. They produce a document for project maintainers outlining their +findings. -**Goals:** Create an action plan/issue backlog of documentation tasks to bring your project up to speed. +**Goals:** Create an action plan/issue backlog of documentation tasks to bring +your project up to speed. -**What we need from you:** Links to all documentation across your entire github org, though writers will focus on what exists in your ‘stated’ website/docs repository. - -> Note: We recommend all CNCF projects request a docs assessment before requesting other services. +**What we need from you:** Links to all documentation across your entire github +org, though writers will focus on what exists in your ‘stated’ website/docs +repository. +> Note: We recommend all CNCF projects request a docs assessment before +> requesting other services. ## Netlify & website setup -**What it is:** We help you set up a website for your project using our preferred Netlify+Hugo+GitHub docs-as-code stack and template. +**What it is:** We help you set up a website for your project using our +preferred Netlify+Hugo+GitHub docs-as-code stack and template. > Note: this setup does not include a site redesign. **Goals:** Gets your project a web presence as quickly as possible. -**What we need from you:** A github repository, preferably named after the website domain name (i.e. longhorn/longhorn.io, rather than longhorn/website) -Netlify installed/added to this repository -A list of key maintainer(s) who should have access to Netlify -A decision on whether your project will use CNCF’s CLA or Github’s DCO for committer verification. - +**What we need from you:** A github repository, preferably named after the +website domain name (i.e. longhorn/longhorn.io, rather than longhorn/website) +Netlify installed/added to this repository A list of key maintainer(s) who +should have access to Netlify A decision on whether your project will use CNCF’s +CLA or Github’s DCO for committer verification. ## Techdocs office hours -**What it is:** An hour long open meeting with CNCF’s technical writers where projects can ask for questions and advice on their documentation. +**What it is:** An hour long open meeting with CNCF’s technical writers where +projects can ask for questions and advice on their documentation. -**Goals:** A way for non-documentation experts to access documentation experts as needed. +**Goals:** A way for non-documentation experts to access documentation experts +as needed. ->Note: Office hours works best for smaller, tactical questions ("I need to write a getting started guide. Where do I start?") For more general questions, we recommend requesting a docs assessment from the team first. +> Note: Office hours works best for smaller, tactical questions ("I need to +> write a getting started guide. Where do I start?") For more general questions, +> we recommend requesting a docs assessment from the team first. **What we need from you:** Show up with a well-scoped question! - ## Website branding & design work -**What it is:** We will do (or contract out) a redesign of your website and add any features you feel you want and can maintain independently, in order for your project to present itself professionally. +**What it is:** We will do (or contract out) a redesign of your website and add +any features you feel you want and can maintain independently, in order for your +project to present itself professionally. -**Goals:** A way for projects that don’t have a supporting organization’s design/web dev departments to have a professional-feeling website, increasing project trust. +**Goals:** A way for projects that don’t have a supporting organization’s +design/web dev departments to have a professional-feeling website, increasing +project trust. -**What we need from you:** A demonstration of need that is scoped enough to draft a statement of work for a contractor, if required. +**What we need from you:** A demonstration of need that is scoped enough to +draft a statement of work for a contractor, if required. -> Note: We are a small team and these projects are time intensive. As such, we can only offer a few slots per year for these kinds of projects. +> Note: We are a small team and these projects are time intensive. As such, we +> can only offer a few slots per year for these kinds of projects. ## Well-scoped writing projects -**What it is:** Have a CNCF technical writer work on a well-scoped, small-to-medium sized writing project that is accomplishable within 1-2 2 week sprints. +**What it is:** Have a CNCF technical writer work on a well-scoped, +small-to-medium sized writing project that is accomplishable within 1-2 2 week +sprints. Examples of well-scoped projects: -- Writing individual tutorial(s), feature documentation, or a getting started guide from scratch +- Writing individual tutorial(s), feature documentation, or a getting started + guide from scratch - Intensive editing for language/grammar of one section of your documentation -- Review of your information architecture (documentation organization/structure) and proposing improvements - +- Review of your information architecture (documentation organization/structure) + and proposing improvements Examples of poorly scoped projects: -- Asking for help to “Improve” a section of documentation +- Asking for help to “Improve” a section of documentation - “Write tutorials” -**Prerequisites:** A completed documentation assessment which outlines the need for a specific kind of documentation that does not exist already. +**Prerequisites:** A completed documentation assessment which outlines the need +for a specific kind of documentation that does not exist already. -**Goals:** Improve your documentation in measurable ways that you may not have the resources to accomplish. +**Goals:** Improve your documentation in measurable ways that you may not have +the resources to accomplish. -**What we need from you:** A ‘point person’ or maintainer knowledgeable in the area they’re being asked to work on to ask questions to be available 1-5 hours/week for the duration of the project. +**What we need from you:** A ‘point person’ or maintainer knowledgeable in the +area they’re being asked to work on to ask questions to be available 1-5 +hours/week for the duration of the project. ## Longer technical writer engagements -**What it is:** A CNCF technical writer embeds with your project for 3-6 months and works on it full-time. +**What it is:** A CNCF technical writer embeds with your project for 3-6 months +and works on it full-time. -**Prerequisites:** A completed documentation assessment which outlines the need for an embedded writer. +**Prerequisites:** A completed documentation assessment which outlines the need +for an embedded writer. **Goals:** Bring your project to a minimum level -**What we need from you:** A well-scoped draft project proposal when you make a formal request. Bear in mind that this project proposal will convert to the statement of work for a contractor and plan accordingly. - -> Note: Longer techncial writer engagements are subject to team availability and CNCF priorities. Availability is not guaranteed. +**What we need from you:** A well-scoped draft project proposal when you make a +formal request. Bear in mind that this project proposal will convert to the +statement of work for a contractor and plan accordingly. +> Note: Longer techncial writer engagements are subject to team availability and +> CNCF priorities. Availability is not guaranteed. diff --git a/docs/versioning-documentation.md b/docs/versioning-documentation.md index 484fb4c..02e81ea 100644 --- a/docs/versioning-documentation.md +++ b/docs/versioning-documentation.md @@ -4,7 +4,8 @@ Technical Documents Versioning is an intersection of: **Changes** + **Language** + **Navigation** + **Search** -For small to medium sized sites using one language/location, a folder based method is likely the best method to balance these considerations. +For small to medium sized sites using one language/location, a folder based +method is likely the best method to balance these considerations. Things discussed in this article: @@ -18,29 +19,42 @@ Things discussed in this article: What are the main concerns when versioning technical documentation in a website? **Readers** + - Ease of navigation/understanding **Maintainers / Writers** + - How hard is it to update when it's time to cut a new version? **Necessity** + - Does the documentation need versioning yet? -- YAGNI (You aren't gonna need it - Don't implement things before you actually need them) +- YAGNI (You aren't gonna need it - Don't implement things before you actually + need them) **Navigation** -- Differences between versions (how do you deal with pages that have been added, removed, or moved between releases?) + +- Differences between versions (how do you deal with pages that have been added, + removed, or moved between releases?) **Searchability** -- Does the duplication of pages affect search results? How do you manage result priority between versions? + +- Does the duplication of pages affect search results? How do you manage result + priority between versions? **Localization / Internationalization** -- How does the added complexity of language/locale versions affect the version system? + +- How does the added complexity of language/locale versions affect the version + system? **Compartmentalization** + - Does all of the site need to be versioned? -- How do we avoid versioning the entire site if only Documentation versions are the goal? +- How do we avoid versioning the entire site if only Documentation versions are + the goal? **Switchability** + - How easy is it to change versioning schemes? ## Versioning Schemes @@ -48,18 +62,21 @@ What are the main concerns when versioning technical documentation in a website? For a Hugo / Netlify setup: | friendly schemes | unfriendly schemes | -| :--- | :--- | +| :------------------- | :----------------- | | None (don't version) | | | Folder based | Query Strings | | Subdomain based | Cookies | -Because Hugo is a static site generator, and Netlify abstracts a lot of the server away Query Strings and Cookies don't really work for a Hugo / Netlify site. +Because Hugo is a static site generator, and Netlify abstracts a lot of the +server away Query Strings and Cookies don't really work for a Hugo / Netlify +site. ### Folder based ![Folder based](./images/folder-based-etcd.png) -Each version of the documentation is placed in its own folder. This is probably the easiest way to start versioning. +Each version of the documentation is placed in its own folder. This is probably +the easiest way to start versioning. ``` content @@ -71,34 +88,42 @@ content └── v3.4.0 ``` -Scores high on: - Maintainer ease of updates - Compartmentalization -Scores low on: - Localization / Internationalization +Scores high on: - Maintainer ease of updates - Compartmentalization Scores low +on: - Localization / Internationalization #### Folder based navigation code example The folder based method of versioning can make the website code more complex. -One of the things that make this an interesting example is how Batard (2020, L8-L18)[2](#footnote2) manages the navigation in the `/site/layouts/docs/versions.html` file, particularly the use of the `replace` function to ensure that when the links in the dropdown menu are built, the versioned links reflect the currently loaded page: +One of the things that make this an interesting example is how Batard (2020, +L8-L18)[2](#footnote2) manages the navigation in the +`/site/layouts/docs/versions.html` file, particularly the use of the `replace` +function to ensure that when the links in the dropdown menu are built, the +versioned links reflect the currently loaded page: [velero.io](https://velero.io/) `/site/layouts/docs/versions.html` + ```html
- {{ $original_version := printf "/%s/" .CurrentSection.Params.version }} - {{ $latest_url := replace .Params.url .CurrentSection.Params.version .Site.Params.latest | relURL }} - {{ $currentUrl := .Permalink }} - - {{ range .Site.Params.versions }} - {{ $new_version := printf "/%s/" . }} - {{ . }} - {{ end }} + {{ $original_version := printf "/%s/" .CurrentSection.Params.version }} {{ + $latest_url := replace .Params.url .CurrentSection.Params.version + .Site.Params.latest | relURL }} {{ $currentUrl := .Permalink }} {{ range + .Site.Params.versions }} {{ $new_version := printf "/%s/" . }} + {{ . }} + {{ end }}
``` + Batard (2020, L8-L18)[2](#footnote2) -Folder based versioning can make site *configuration* less complex. +Folder based versioning can make site _configuration_ less complex. velero.io `velero/site/config.yaml` + ```yaml versioning: true latest: v1.5 @@ -109,44 +134,55 @@ velero.io `velero/site/config.yaml` - v1.3.2 ⋮ ``` + Brubaker et al. (2020, L14-L20)[3](#footnote3) ### Subdomain based -The subdomain scheme uses some simpler template code to generate links, only having to update the `.url`, but the Hugo config file is made more complex. +The subdomain scheme uses some simpler template code to generate links, only +having to update the `.url`, but the Hugo config file is made more complex. ![Subdomain based](./images/subdomain-based-k8s.png) Each version of the documentation is its own site + - Uses git feature branches rather than folders to organize versions - Separate site in Netlify for each version supported - Simpler template code, more complex config Scores high on: -- Localization / Internationalization -Scores low on: + +- Localization / Internationalization Scores low on: - Compartmentalization - Maintenance, each version is its own site #### Subdomain based navigation code example -Same style of dropdown function as above, but made simpler because of the configuration: +Same style of dropdown function as above, but made simpler because of the +configuration: https://kubernetes.io `website/layouts/partials/navbar-version-selector.html` ```html -
- {{ $p := . }} - {{ range .Site.Params.versions }} - {{ .version }} - {{ end }} +
+ {{ $p := . }} {{ range .Site.Params.versions }} + {{ .version }} + {{ end }}
``` + Pursley et al. (2020, L4-L9)[4](#footnote4) -The dropdown example is made simpler because the config is more complex and because the server setup is more complex. +The dropdown example is made simpler because the config is more complex and +because the server setup is more complex. https://kubernetes.io `website/config.toml` + ```toml [[params.versions]] fullversion = "v1.20.0" @@ -171,27 +207,42 @@ Version using `folders` if: - maintainer ease of updates is a priority - localization / internationalization not a priority -- it is important that only the documentation is versioned (and not, for instance, the blog) +- it is important that only the documentation is versioned (and not, for + instance, the blog) Version using `subdomains` if: - localization / internationality is planned - compartmentalization not a priority -For small to medium sized sites using one language/location, a folder based method is likely the best method to balance versioning considerations. +For small to medium sized sites using one language/location, a folder based +method is likely the best method to balance versioning considerations. ## References / Credits -1: [Bannister, T.](https://github.com/sftim) et al. (2020, December 23). kubernetes/website. GitHub. Retrieved February 2, 2021 from [https://github.com/kubernetes/website/blob/ 7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml](https://github.com/kubernetes/website/blob/7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml) +1: [Bannister, T.](https://github.com/sftim) et al. +(2020, December 23). kubernetes/website. GitHub. Retrieved February 2, 2021 from +[https://github.com/kubernetes/website/blob/ 7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml](https://github.com/kubernetes/website/blob/7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml) -2: [Batard, T.](https://github.com/tbatard) (2020, August 13). _vmware-tanzu/velero_. GitHub. Retrieved January 19, 2021 from [https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html](https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html) +2: [Batard, T.](https://github.com/tbatard) (2020, +August 13). _vmware-tanzu/velero_. GitHub. Retrieved January 19, 2021 from +[https://github.com/vmware-tanzu/velero/blob/ db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html](https://github.com/vmware-tanzu/velero/blob/db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html) +3: [Brubaker, N.](https://github.com/nrb), +[Rosland, J.](https://github.com/jonasrosland), +[Thompson, C.](https://github.com/carlisia), +[Batard, T.](https://github.com/tbatard) (2020, September 16). +_vmware-tanzu/velero_. GitHub. Retrieved February 2, 2021 from +[https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml](https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml) - 3: [Brubaker, N.](https://github.com/nrb), [Rosland, J.](https://github.com/jonasrosland), [Thompson, C.](https://github.com/carlisia), [Batard, T.](https://github.com/tbatard) (2020, September 16). _vmware-tanzu/velero_. GitHub. Retrieved February 2, 2021 from [https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml](https://github.com/vmware-tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml) - - 4: [Pursley, B.](https://github.com/brianpursley), [Horgan, C.](https://github.com/celestehorgan), Takahashi, S. (2020, July 21). _kubernetes/website_. GitHub. Retrieved February 2, 2021 from [https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html](https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html) +4: [Pursley, B.](https://github.com/brianpursley), +[Horgan, C.](https://github.com/celestehorgan), Takahashi, S. (2020, July 21). +_kubernetes/website_. GitHub. Retrieved February 2, 2021 from +[https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html](https://github.com/kubernetes/website/blob/072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/navbar-version-selector.html) --- -This page has been adapted from the [Technical Documentation Versioning slide show](https://technical-documentation-versioning.netlify.app/), its source can be found here: [https://github.com/nate-double-u/technical-documentation-versioning](https://github.com/nate-double-u/technical-documentation-versioning). - +This page has been adapted from the +[Technical Documentation Versioning slide show](https://technical-documentation-versioning.netlify.app/), +its source can be found here: +[https://github.com/nate-double-u/technical-documentation-versioning](https://github.com/nate-double-u/technical-documentation-versioning). diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index e57e517..6d4f91a 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -1,31 +1,50 @@ # CNCF website guidelines checklist -As per the [CNCF Website Guidelines](https://github.com/cncf/foundation/blob/master/website-guidelines.md), the following should be present:
-*Note*, not all of these are applicable to all projects +As per the +[CNCF Website Guidelines](https://github.com/cncf/foundation/blob/master/website-guidelines.md), +the following should be present:
_Note_, not all of these are applicable to +all projects - [ ] 1. Website should be [hosted in an open source repo](./repo-setup.md) - [ ] Hosted in the same organization as the main project - [ ] Setup [DCO](https://github.com/apps/dco) or CLA (DCO recommended) - CNCF's IP policy (https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) requires all projects to use either CLA (Contributor License Agreements) or [DCO (Developer Certificate of Origin)](https://github.com/apps/dco). Unless there's a strong necessity to use CLA, we encourage projects to use DCO as it's easier to setup and use. -- [ ] 2. Reference the origin company correctly (if needed)
- *Note*: It is OK to say that, e.g., “Prometheus was originally created by Soundcloud” or “Kubernetes builds upon 15 years of experience of running production workloads at Google,” but the origin company should not otherwise be referred to on the project homepage. -- [ ] 3. No links or forms for capturing enterprise support leads should be present
- *Note*: It is fine to have an enterprise support, commercial partners or similar page. - - [ ] If page is present, the companies list is alphabetized or randomized on load. + CNCF's IP policy (https://github.com/cncf/foundation/blob/master/charter.md#11-ip-policy) + requires all projects to use either CLA (Contributor License Agreements) + or [DCO (Developer Certificate of Origin)](https://github.com/apps/dco). + Unless there's a strong necessity to use CLA, we encourage projects to use + DCO as it's easier to setup and use. +- [ ] 2. Reference the origin company correctly (if needed)
_Note_: It is + OK to say that, e.g., “Prometheus was originally created by Soundcloud” or + “Kubernetes builds upon 15 years of experience of running production + workloads at Google,” but the origin company should not otherwise be + referred to on the project homepage. +- [ ] 3. No links or forms for capturing enterprise support leads should be + present
_Note_: It is fine to have an enterprise support, commercial + partners or similar page. + - [ ] If page is present, the companies list is alphabetized or randomized on + load. - [ ] If page is present, the vetting of companies listed is complete
- *Note*: Projects are welcome to outsource this vetting to CNCF staff if it becomes a burden. -- [ ] 4. Links to companies offering support go to a page that at least mentions support of the project -- [ ] 5. Copyright notice present at bottom of page.
- Copyright should be to the project authors or to CNCF, not the origin company. For details, see [Copyright notices](https://github.com/cncf/foundation/blob/master/copyright-notices.md). + _Note_: Projects are welcome to outsource this vetting to CNCF staff if + it becomes a burden. +- [ ] 4. Links to companies offering support go to a page that at least mentions + support of the project +- [ ] 5. Copyright notice present at bottom of page.
Copyright should be to + the project authors or to CNCF, not the origin company. For details, see + [Copyright notices](https://github.com/cncf/foundation/blob/master/copyright-notices.md). - [ ] 6. CNCF Branding elements - - [ ] “We are a Cloud Native Computing Foundation project.” or “We are a Cloud Native Computing Foundation sandbox project.” present (depending on status) + - [ ] “We are a Cloud Native Computing Foundation project.” or “We are a Cloud + Native Computing Foundation sandbox project.” present (depending on + status) - [ ] CNCF logo near the bottom of their project homepage - - [ ] *Optionally* link to KubeCon + CloudNativeCon as the events approach + - [ ] _Optionally_ link to KubeCon + CloudNativeCon as the events approach - [ ] 7. Page footer contents - - [ ] Trademark guidelines by either linking to Trademark Usage (directly or via a "Terms of service" page), or by including the following text:
- "The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see [Trademark Usage](https://www.linuxfoundation.org/trademark-usage/)". + - [ ] Trademark guidelines by either linking to Trademark Usage (directly or + via a "Terms of service" page), or by including the following text:
+ "The Linux Foundation® (TLF) has registered trademarks and uses + trademarks. For a list of TLF trademarks, see + [Trademark Usage](https://www.linuxfoundation.org/trademark-usage/)". -## Community and license files +## Community and license files The following files should be in the root of the repository: