cncf
/
techdocs
mirror of https://github.com/cncf/techdocs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[editorial] Fix format of analyses, docs, and README 

- No content changes

Signed-off-by: Patrice Chalin <pchalin@gmail.com>
This commit is contained in:
Patrice Chalin 2024-05-31 13:15:12 -04:00
parent 01e6b66e91
commit 31f8d6f787
50 changed files with 5196 additions and 2620 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
.github/settings.yml vendored
View File

@ -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

9
.prettierignore
View File

@ -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.

29
README.md
View File

@ -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.
The `docs/` directory contains collected resources for building websites and
developing documentation, including recommended tools and practices, how-tos,
and evaluation checklists.

334
analyses/0001-contour.md
View File

@ -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.
- **Information Architecture**:
- **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.
- 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 `<h2>` 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 `<h2>` 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:
- 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
- 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
### 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.
Docs+Code combined repositories are a long-term risk. We strongly recommend decoupling these into their own repositories.
1. Figure out any code-related dependencies, i.e. API documentation that might
be autogenerated, and figure out how to decouple this.
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.
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.
3. Develop a maintainers list/maintenance plan for the documentation and its
repository.

265
analyses/0002-notary-project.md
View File

@ -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.
- 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.
- Is the documentation feature complete, as in each product feature is
documented?
- 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 &mdash; linking to it directly during the development process, and planning documentation along side the development of the system as a whole.
- 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 &mdash; 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
<!-- borrowed from @celestehorgan's excellent work in 0001-contour.md -->
- 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
- [ ] 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.
_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.

307
analyses/0003-krator.md
View File

@ -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.
<!-- borrowed from @celestehorgan's excellent work in 0001-contour.md -->
- **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.
- **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
## 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 and recommendations
Communication methods will need to be determined and added to [CONTRIBUTING.md](https://github.com/krator-rs/krator/blob/main/CONTRIBUTING.md).
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.
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.
<!-- borrowed from @celestehorgan's excellent work in 0001-contour.md -->
- **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. 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. 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
- 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

456
analyses/0004-tremor.md
View File

@ -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.
- **Information Architecture:** Project Tremor's documentation makes a number of
individually small IA choices that culminate in a confusing experience for the
user.
- **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.
- 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.
- **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?
- **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?
- **Get specific about your Getting Started:** Getting Started Guides contain a
very predictable set of content:
- **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/)
- 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 [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/)
- **Reorganize the Operations section and retitle it "Using Tremor"**:
Additionally, move some topics from the existing Getting Started section:
- **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/)).
- [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
- **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.
- **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!
- **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.
- 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.
- **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.
- **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!
- 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?
- **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.
- **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**
- 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.
- 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)
- 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:
**Reorganize the top-level navigation of the site:** once again, as mentioned
previously:
- Getting Started
- 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.

270
analyses/0005-fluxcd.md
View File

@ -1,11 +1,12 @@
# Assessment template
Prepared by: Celeste Horgan ([@celestehorgan](https://github.com/cncf/techdocs))<br>
Date: 2021-11-30
Prepared by: Celeste Horgan
([@celestehorgan](https://github.com/cncf/techdocs))<br> 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**:
**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.
- 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**:
**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!
- 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**:
**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 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.
- 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.
- 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.
**Content creation processes**:
- 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.
- The [Contributing Guide](https://fluxcd.io/docs/contributing/docs/) contains really thorough documentation on contributing to both docs and the project itself!
**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
- 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**:
**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.
- 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.
- 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.
- [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!
**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.

247
analyses/0006-gateway-api.md
View File

@ -1,11 +1,13 @@
# Assessment: Project Kubernetes Gateway API
Prepared by: Meha Bhalodiya ([@mehabhalodiya](https://github.com/mehabhalodiya))<br>
Date: 2021-03-03
Prepared by: Meha Bhalodiya
([@mehabhalodiya](https://github.com/mehabhalodiya))<br> 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**:
**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.
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 <code>[good first issue](https://github.com/kubernetes-sigs/gateway-api/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)</code> label. To invite new contributors, consider filing issues that are easy to remedy, label them accordingly (try keeping up-to-date, seems many are <code>[frozen](https://github.com/kubernetes-sigs/gateway-api/issues?q=is%3Aopen+is%3Aissue+label%3Alifecycle%2Ffrozen)</code>), 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
<code>[good first issue](https://github.com/kubernetes-sigs/gateway-api/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)</code>
label. To invite new contributors, consider filing issues that are easy to
remedy, label them accordingly (try keeping up-to-date, seems many are
<code>[frozen](https://github.com/kubernetes-sigs/gateway-api/issues?q=is%3Aopen+is%3Aissue+label%3Alifecycle%2Ffrozen)</code>),
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.

202
analyses/0007-porter.md
View File

@ -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/)
- [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/
- Mixins & Plugins sections duplicated in sidebar (and could potentially be organized under Concepts?)
- 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/
- 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.

25
analyses/0008-backstage/README.md
View File

@ -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.

503
analyses/0008-backstage/backstage-analysis.md
View File

@ -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:
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.
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).
- 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).
**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.
**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.
**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.
<!--- References --->
[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/
<!--- internal refs --->
[contrib-doc-rec]: #recommendations-contributor-documentation
[contributor-doc]: #contributor-documentation
[doc-survey]: ./Backstage%20doc%20survey.csv

115
analyses/0008-backstage/backstage-glossary.md
View File

@ -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.

278
analyses/0008-backstage/backstage-implementation.md
View File

@ -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.
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. |
| 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.
**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
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.
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.
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. 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
- 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.
<!--- References --->
[backstage-analysis]: ./backstage-analysis.md

125
analyses/0008-backstage/backstage-insights-summary.md
View File

@ -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.
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.
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:
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
- DevEx Engineering Manager (2)
- Staff Engineer
- Software Architect
- QA Manager
- Technical PM
- IT Engineering Manager
- Engineering Manager
- Site Reliability Engineer

118
analyses/0008-backstage/backstage-issues.md
View File

@ -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

59
analyses/0008-backstage/user-roles.md
View File

@ -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:
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.
- 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. |
| 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.
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.

36
analyses/0009-in-toto/README.md
View File

@ -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)

397
analyses/0009-in-toto/in-toto-analysis.md
View File

@ -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,89 +78,11 @@ 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 | | |
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**:
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**:
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 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.
**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).
**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.
**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.
- 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.
## 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 | |
| -------------------------- | --- | --- | --- | --- | --- |
| Information architecture | | | x | | |
| New user content | | | x | | |
| Content maintainability | | | x | | |
| Content creation processes | | | x | | |
Scale:
@ -143,63 +92,211 @@ Scale:
### Comments
**Communication methods documented**: A Contact channels list is available from home page under Community > Contact.
**Information Architecture**:
**Beginner friendly issue backlog**: A "Good First Issue" label is available and used for PRs for specific implementations. Not in much general use.
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.
**“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).
- 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.
**Project governance documentation**: Clearly described and discoverable on GOVERNANCE page.
**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**:
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 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.
**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).
**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.
**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.
- 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.
## 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 | |
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**: 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.
**“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.
### 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.

170
analyses/0009-in-toto/in-toto-doc-issues.md
View File

@ -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.
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**
## 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**.
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)
- [ ] 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.
This is a necessary step in raising the maturity level of this project. The
roadmap should initially describe and provide access to:
- [ ] 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.
- 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.
- [ ] Create a doc contributors policy requiring that the Doc home page be updated to reflect any changes to the doc locations and 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.
## Expose new-user information
- [ ] Create a doc contributors policy requiring that the Doc home page be
updated to reflect any changes to the doc locations and structure.
- [ ] 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.
## Expose new-user information
- [ ] As a stop-gap, add a top-level TOC for the existing Specification to show what is in it.
- [ ] Move the content of the
[README for the main repo](https://github.com/in-toto/in-toto) to a
separate **"Getting Started" document**.
- [ ] 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.
- [ ] 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.
## 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.)
- [ ] 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.
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...).
- [ ] 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.
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.)
- [ ] 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
- [ ] 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.
- [ ] 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.
- [ ] As documents are transfered from GitHub into the Doc web site, update the
index accordingly and adjust the doc architecture as needed.
## Establish policy for reference material
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.
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.
- [ ] Decide where reference docs for different implementations should live in the doc structure and where their sources live in the repo structure.
- [ ] Decide where reference docs for different implementations should live in
the doc structure and where their sources live in the repo structure.
- [ ] 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.
- [ ] 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.
## Define content creation process
- [ ] 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).
- [ ] 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.
- [ ] 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.
- [ ] 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.

283
analyses/0009-in-toto/in-toto-implementation.md
View File

@ -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:
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.
- 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.
To efficiently transfer relevant information to the people who need it, organize
documentation with the product users' roles in mind. For example:
Similarly, the depth and detail of introductory conceptual material should be clearly addressed to and tailored to:
- 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.
- *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.
Similarly, the depth and detail of introductory conceptual material should be
clearly addressed to and tailored to:
See a more detailed analysis of reader roles and their documentation needs below.
- _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.
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.
Users with the following roles are potential audiences for in-toto project documentation.
- 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.
| 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) |
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:
- [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)
d. Expose parts of the product specification as separate named documents on
the website, as:
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.
- [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)
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.
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.
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**
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**.
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.
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.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.3 Create a doc contributors policy requiring that the Doc home page be updated to reflect any changes to the doc locations and structure.
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.
2. Expose new-user information
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.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. Expose new-user information
2.2 As a stop-gap, add a top-level TOC for the existing Specification to show what is in it.
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.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.
2.2 As a stop-gap, add a top-level TOC for the existing Specification to show
what is in it.
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.)
2.3 Move important sections out of the spec into separate documents, and add
them to the Doc home-page TOC.
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.
- 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.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. 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...).
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
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.)
4. Sort the layered technical overviews by increasing depth, and use that as a guide to create the overall doc architecture.
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.
- 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.
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.
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.

64
analyses/0009-in-toto/survey-of-existing-doc.md
View File

@ -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

10
analyses/0010-etcd/README.md
View File

@ -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).

621
analyses/0010-etcd/etcd-analysis.md
View File

@ -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 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.
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.
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.
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].
**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.
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.
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.
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.
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.
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 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.
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.
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/).
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.
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?).
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.
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.
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".
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].
- **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.
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.
For an excellent and very literal example of this approach, see the [Kubernetes
documentation][k8s-doc].
Fill in missing instructional documentation. Most notably, write (or link to) instructions for installing on Kubernetes and Linux, and on using Authentication.
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 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 | *********** |
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 | \*\*\*\*\*\*\*\*\*\*\* |
### 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.
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.
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 |
| 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.
- Account custodians are not clearly documented.
### 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.
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.
<!--- References --->
[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

284
analyses/0010-etcd/etcd-implementation.md
View File

@ -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
<!--- References --->
[etcd-analysis]: ./etcd-analysis.md

293
analyses/0010-etcd/etcd-issues.md
View File

@ -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.
In each user role section, provide a link to the beginning of a "getting
started" workflow, either a Quick-start or Installation instructions.
## Issue: Convert Tutorials to Tasks
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.
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.
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".
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/`.
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). |
| 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.
<!--- References --->

10
analyses/0011-keda/README.md
View File

@ -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).

428
analyses/0011-keda/keda-analysis.md
View File

@ -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.
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.
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 |
| 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.
<!--- References --->

175
analyses/0011-keda/keda-implementation.md
View File

@ -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.
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*
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):
Document in the repo (keda-docs, keda, or both) who the website/documentation maintainers are.
- 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.
# 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.
<!--- References --->

234
analyses/0011-keda/keda-issues.md
View File

@ -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.
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).
- [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.
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.
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.
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.*
- [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".
- 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.
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))
- [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.
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.
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.
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.
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". |
| 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".

62
analyses/README.md
View File

@ -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.

7
docs/README.md
View File

@ -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!

3
docs/analysis/README.md
View File

@ -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.

211
docs/analysis/criteria.md
View File

@ -4,69 +4,79 @@
### Information architecture
The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following:
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?
- 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?

192
docs/analysis/howto.md
View File

@ -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:
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.).
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:
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.
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:
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.
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.
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:
- 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.
Rewrite each action in the implementation plan. If possible, break large actions
into smaller issues. Each issue should be:
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.
- 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.
## 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.

20
docs/analysis/resources/README.md
View File

@ -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
[criteria]: ../criteria.md

335
docs/analysis/resources/analysis-template.md
View File

@ -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
<!-- Pick the CNCF maturity level of the project: -->
_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.
<!-- or -->
_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.
<!-- For each heading below, discuss how well the in-scope items, and especially the technical documentation, meet these criteria. (Criteria are copied from criteria.md) -->
### Information architecture
The overall structure (pages/subpages/sections/subsections) of your project documentation. We evaluate on the following:
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?
- 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
<!-- Pick the CNCF maturity level of the project: -->
_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.
<!-- or -->
_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) |
<!-- Rating values:
1 - not present
@ -213,46 +278,52 @@ _PROJECT_ is an **incubating** project of CNCF. This means that the project shou
5 - exemplary
-->
## Comments
<!--
Make any overall comments about the Contributor Documentation here.
-->
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.
<!-- For each heading below, discuss how well the in-scope items meet these criteria. Keep in mind that much of the contributor documentation might be contained in the documentation repository. (Criteria are copied from criteria.md) -->
### 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
<!-- Pick the CNCF maturity level of the project: -->
_PROJECT_ is a **graduated** project of CNCF. This means that the project should have [*very high*][criteria-doc] standards for documentation.
<!-- or -->
_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 a **graduated** project of CNCF. This means that the project should
have [_very high_][criteria-doc] standards for documentation.
<!-- or -->
_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
<!--
Make any overall comments about the Website and documentation infrastructure here.
-->
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.
<!-- For each heading below, discuss how well the in-scope items meet these criteria. Keep in mind that much of the website infrastructure criteria depend on the tools (static site generator, website framework and hosting, analytics tools, etc.) and processes (project CI, release procedures, goverance, etc.) used to produce the documentation. (Criteria are copied from criteria.md) -->
### 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
<!--- References --->
[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

18
docs/analysis/resources/implementation-template.md
View File

@ -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
<!--- References --->
[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119

20
docs/analysis/resources/issue-template.md
View File

@ -11,19 +11,24 @@ tags: _PROJECT_
Audience: <!-- Provide the user role to which the issue is most applicable. -->
Type: <!-- What type of documentation topic the change affects. One of Task, Reference, or Conceptual. -->
Type:
<!-- What type of documentation topic the change affects. One of Task, Reference, or Conceptual. -->
# Context
<!-- This is boilerplate text linking back to the doc analysis. -->
<!-- This is boilerplate text linking back to the doc analysis. -->
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
<!-- Include a bullet list of links to pages that are affected by the change: -->
Related material in the current doc:
- https://github.com/_PROJECT_/website/tree/main/content/en/docs/v3.5/tutorials
<!-- Describe in detail a suggested way to achieve the goals of the issue. This should be specific enough to provide a contributor with a recipe for making the change; however, the contributor should feel free to solve the problem differently if they have an idea how it should be done. -->
@ -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.)

8
docs/analysis/resources/umbrella-issue-template.md
View File

@ -11,14 +11,18 @@ tags: _PROJECT_
<!-- The following is boilerplate language to include in the umbrella issue in the repo: -->
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

38
docs/analytics.md
View File

@ -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.<br>
This will open an analytics console onto your GA4 site tag. Perform the
remaining steps from your GA4 console.
of your UA property.<br> 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 `<head>` element
of your website pages, _provided that Hugo is building in a production
environment_.
GA4 measurement ID. Conditionally include this partial in the `<head>`
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

93
docs/assistance.md
View File

@ -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:
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. 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:
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.
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.

4
docs/hugo-and-docsy.md
View File

@ -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

9
docs/localization/README.md
View File

@ -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.

42
docs/netlify-domains-setup.md
View File

@ -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.
Issues related to these should be forwarded on to Linux Foundation IT staff.

55
docs/repo-setup.md
View File

@ -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.

50
docs/searching-documentation.md
View File

@ -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)
- [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.
## 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).

97
docs/services.md
View File

@ -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.

133
docs/versioning-documentation.md
View File

@ -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)<sup>[2](#footnote2)</sup> 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)<sup>[2](#footnote2)</sup> 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
<div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
{{ $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/" . }}
<a class="dropdown-item"
href="{{ replace $currentUrl $original_version $new_version | relURL }}">{{ . }}</a>
{{ 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/" . }}
<a
class="dropdown-item"
href="{{ replace $currentUrl $original_version $new_version | relURL }}"
>{{ . }}</a
>
{{ end }}
</div>
```
Batard (2020, L8-L18)<sup>[2](#footnote2)</sup>
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)<sup>[3](#footnote3)</sup>
### 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
<div class="dropdown-menu dropdown-menu-right" aria-labelledby="navbarDropdownMenuLink">
{{ $p := . }}
{{ range .Site.Params.versions }}
<a class="dropdown-item" href="{{ .url }}{{ $p.RelPermalink }}">{{ .version }}</a>
{{ end }}
<div
class="dropdown-menu dropdown-menu-right"
aria-labelledby="navbarDropdownMenuLink"
>
{{ $p := . }} {{ range .Site.Params.versions }}
<a class="dropdown-item" href="{{ .url }}{{ $p.RelPermalink }}"
>{{ .version }}</a
>
{{ end }}
</div>
```
Pursley et al. (2020, L4-L9)<sup>[4](#footnote4)</sup>
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
<a name="footnote1">1</a>: [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)
<a name="footnote1">1</a>: [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)
<a name="footnote2">2</a>: [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)
<a name="footnote2">2</a>: [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)
<a name="footnote3">3</a>: [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)
<a name="footnote3">3</a>: [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)
<a name="footnote4">4</a>: [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)
<a name="footnote4">4</a>: [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).

53
docs/website-guidelines-checklist.md
View File

@ -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:<br/>
*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:<br/> _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)<br/>
*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<br/>
*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)<br/> _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<br/> _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<br/>
*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.<br/>
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.<br/> 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:<br/>
"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:<br/>
"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: