diff --git a/.cspell.yml b/.cspell.yml index 16e7762..c13d3e9 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -24,9 +24,12 @@ words: - CLOTributor - CNCF - Docsy + - dwelsch - keda + - knative - kedacore - krook + - mkdocs - nate - nvmrc - subpages @@ -34,3 +37,4 @@ words: - toolkits - toto - triaging + - Welsch diff --git a/analyses/0001-contour.md b/analyses/0001-contour.md index f5b0f1f..4c20b34 100644 --- a/analyses/0001-contour.md +++ b/analyses/0001-contour.md @@ -47,7 +47,6 @@ criterion’s definition. ### 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 @@ -83,7 +82,6 @@ criterion’s definition. - 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. @@ -111,7 +109,6 @@ criterion’s definition. ### 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 @@ -139,7 +136,6 @@ criterion’s definition. a small win and a great first issue. - **New user content**: - - Work with a technical writer to revise your getting started page to provide a bit more background information about Contour for the true new learner and provide more "next steps" documentation. @@ -221,7 +217,6 @@ website, and in the repo. Great job team! - **Branding and design**: one extremely small styling suggestion which would make a great first issue: - - for `

` elements on documentation pages, change the margin from `margin-bottom: 2rem` to `margin-top: 1rem; margin-bottom: 1rem` or (preferred) `margin-top: 1.5rem; margin-bottom: 0.5rem;`. In general it's @@ -266,7 +261,6 @@ website, and in the repo. Great job team! 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 diff --git a/analyses/0002-notary-project.md b/analyses/0002-notary-project.md index bb1b7eb..bbadd5b 100644 --- a/analyses/0002-notary-project.md +++ b/analyses/0002-notary-project.md @@ -75,7 +75,6 @@ Criteria: - 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 @@ -86,14 +85,12 @@ Criteria: - Are there step-by-step instructions (tasks, tutorials) documented for features? - - Since V2's documentation is so conceptual at this point (consisting mostly of specification), it may be best to leave it as is — linking to it directly during the development process, and planning documentation along side the development of the system as a whole. - Is the “happy path”/most common use case documented? - - The V1 Getting Started Guide is very good. Will V2 be able to draw from it? - If the documentation does not suffice, is there a clear escalation path for @@ -181,7 +178,6 @@ 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. @@ -190,7 +186,6 @@ Criteria 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 diff --git a/analyses/0003-krator.md b/analyses/0003-krator.md index 9e6f5c6..5186a46 100644 --- a/analyses/0003-krator.md +++ b/analyses/0003-krator.md @@ -54,7 +54,6 @@ Criteria: ### 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) diff --git a/analyses/0004-tremor.md b/analyses/0004-tremor.md index 71500f9..53fd6fd 100644 --- a/analyses/0004-tremor.md +++ b/analyses/0004-tremor.md @@ -52,7 +52,6 @@ Scale: - **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. @@ -112,7 +111,6 @@ Scale: - **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 @@ -172,7 +170,6 @@ Scale: - **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? @@ -183,7 +180,6 @@ Scale: - **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/) @@ -207,7 +203,6 @@ Scale: - **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 @@ -218,7 +213,6 @@ Scale: - **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. @@ -269,7 +263,6 @@ Scale: 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 @@ -280,7 +273,6 @@ Scale: [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. @@ -296,7 +288,6 @@ Scale: - **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 @@ -325,7 +316,6 @@ 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 @@ -340,7 +330,6 @@ Scale: 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. diff --git a/analyses/0005-fluxcd.md b/analyses/0005-fluxcd.md index e5f2675..d86bac6 100644 --- a/analyses/0005-fluxcd.md +++ b/analyses/0005-fluxcd.md @@ -89,7 +89,6 @@ Scale: 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 diff --git a/analyses/0006-gateway-api.md b/analyses/0006-gateway-api.md index ed1433e..073165d 100644 --- a/analyses/0006-gateway-api.md +++ b/analyses/0006-gateway-api.md @@ -92,7 +92,6 @@ as well as where to find them. - 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 @@ -270,7 +269,6 @@ The [website](https://gateway-api.sigs.k8s.io/) is accessible via HTTPS. [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) diff --git a/analyses/0007-porter.md b/analyses/0007-porter.md index d9e3bf0..34bec4c 100644 --- a/analyses/0007-porter.md +++ b/analyses/0007-porter.md @@ -69,14 +69,12 @@ Scale: - 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 diff --git a/analyses/0008-backstage/backstage-analysis.md b/analyses/0008-backstage/backstage-analysis.md index eee1d3c..281db93 100644 --- a/analyses/0008-backstage/backstage-analysis.md +++ b/analyses/0008-backstage/backstage-analysis.md @@ -118,11 +118,11 @@ such, and pertain to legal requirements such as copyright and licensing issues. | 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: @@ -352,10 +352,10 @@ these navigation aids are adequate. | 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: @@ -423,19 +423,19 @@ from the product documentation. | 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: diff --git a/analyses/0008-backstage/backstage-implementation.md b/analyses/0008-backstage/backstage-implementation.md index 0668d23..2bb9916 100644 --- a/analyses/0008-backstage/backstage-implementation.md +++ b/analyses/0008-backstage/backstage-implementation.md @@ -153,7 +153,6 @@ 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. Download and install any necessary software components 1. Integrate Backstage with an existing development environment diff --git a/analyses/0009-in-toto/in-toto-doc-issues.md b/analyses/0009-in-toto/in-toto-doc-issues.md index fdc94a0..29f61b9 100644 --- a/analyses/0009-in-toto/in-toto-doc-issues.md +++ b/analyses/0009-in-toto/in-toto-doc-issues.md @@ -21,7 +21,6 @@ repurposed as the new overall **Doc home page**. 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 @@ -40,7 +39,6 @@ repurposed as the new overall **Doc home page**. - [ ] 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 diff --git a/analyses/0009-in-toto/in-toto-implementation.md b/analyses/0009-in-toto/in-toto-implementation.md index 68f15f0..06ac4f3 100644 --- a/analyses/0009-in-toto/in-toto-implementation.md +++ b/analyses/0009-in-toto/in-toto-implementation.md @@ -88,7 +88,6 @@ following general plan. 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 and current website About - create versions of increasing depth to address to specific audiences) @@ -159,7 +158,6 @@ following general plan. 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 @@ -229,7 +227,6 @@ following general plan. 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) @@ -252,7 +249,6 @@ following general plan. 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 diff --git a/analyses/0009-in-toto/survey-of-existing-doc.md b/analyses/0009-in-toto/survey-of-existing-doc.md index b9903c8..5405ccc 100644 --- a/analyses/0009-in-toto/survey-of-existing-doc.md +++ b/analyses/0009-in-toto/survey-of-existing-doc.md @@ -33,7 +33,6 @@ https://github.com/in-toto/attestation https://github.com/in-toto/demo - Doc generation repo: https://github.com/in-toto/docs - - Generated (read-the-docs) for Python reference implementation - Installation https://in-toto.readthedocs.io/en/latest/installing.html diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md index e83c670..fb21cfa 100644 --- a/analyses/0012-TUF/implementation.md +++ b/analyses/0012-TUF/implementation.md @@ -27,7 +27,6 @@ pertain to legal requirements such as copyright and licensing issues. The top-level documentation recommendations for this project are: - **Reorganize documentation** - - Introduce a docs section and place some sections like **Getting started** under it to avoid repetition - Structure 'Getting started' according to user roles @@ -35,7 +34,6 @@ The top-level documentation recommendations for this project are: easier to find. - **Introduce instructional documentation** - - Identify TUF user roles (personas) - Develop task-based material i.e How-tos for user roles - Develop quick start and contribution guides for new users @@ -65,7 +63,6 @@ structure: - **Home page** - **Documentation**: Overview of TUF - - Overview: Metadata,Project,Security - Getting started: Adopters, contributors, - History @@ -74,7 +71,6 @@ structure: - FAQ - **Community**: You can have two sections. - - Learn and connect: Includes all community communication channels including social media, mailing lists, calendars, Slack, etc. - Develop and Contribute: Information about how to contribute to TUF @@ -102,7 +98,6 @@ Contributors: - **Adopters**: Integrate TUF security properties into new and existing content delivery systems. Adopters can be classified into two categories: - - _Client maintainers_: depend on repository maintainers, to provide a TUF repo. And they can choose from multiple TUF client implementations (python-tuf, go-tuf, etc.) Typically, they will pick the language their diff --git a/analyses/0015-knative/analysis.md b/analyses/0015-knative/analysis.md index e985156..5507738 100644 --- a/analyses/0015-knative/analysis.md +++ b/analyses/0015-knative/analysis.md @@ -6,7 +6,7 @@ modified: 2025-07-25 author: Dave Welsch (@dwelsch-esi) --- - + ## Introduction @@ -22,12 +22,11 @@ efforts. ### Purpose -This document was written to analyze the current state of Knative -documentation. It aims to provide project leaders with an informed understanding -of potential problems in current project documentation. A second -document is a list 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 Knative documentation. +It aims to provide project leaders with an informed understanding of potential +problems in current project documentation. A second document is a list of +[issues] to be added to the project documentation repository. These issues can +be taken up by contributors to improve the documentation. This document: @@ -42,8 +41,8 @@ the technical documentation, and documentation for contributors and users on the Knative GitHub repository. The Knative website and documentation are written in Markdown and are compiled -using the mkdocs static site generator with the Material theme. -The site's code is stored on the knative/docs GitHub repo. +using the mkdocs static site generator with the Material theme. The site's code +is stored on the knative/docs GitHub repo. #### In scope @@ -84,8 +83,8 @@ Each section begins with summary ratings based on a rubric with appropriate - **Recommendations**: suggested changes that would improve the effectiveness of the documentation. -The accompanying [issues] document contains actionable improvements -for inclusion in [project-doc-website]/issues. +The accompanying [issues] document contains actionable improvements for +inclusion in [project-doc-website]/issues. ### How to use this document @@ -121,7 +120,7 @@ Knative is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. | Criterion | [Rating (1-5)] | -| -------------------------- | -------------- | +| -------------------------- | --------------------- | | Information architecture | 2 - Needs improvement | | New user content | 2 - Needs improvement | | Content maintainability | 3 - Meets standards | @@ -136,23 +135,23 @@ around organization and the new user experience. Following are general comments that don't address specific CNCF criteria. The project main landing page also serves as the documentation landing page, -mixing marketing and technical information. It's helpful to users if there's -a clear separation between technical documentation and other information. -The technical documentation is goal-driven and should be factual, specific, -and purposeful. +mixing marketing and technical information. It's helpful to users if there's a +clear separation between technical documentation and other information. The +technical documentation is goal-driven and should be factual, specific, and +purposeful. The technical documentation outline in the banner headings is good from a organizational perspective: Concepts, Tutorial, and Installing, then instructional information, then reference information. See notes below on the Left-hand sidebar (LHS) table of contents. Some other notes: -- The "Home" item is unnecessary for the project landing page. By convention -the upper-left logo links to the site landing page. -- The "Concepts" section is a brief introduction. Instead, it should contain -a complete technical overview that's accessible to a new user. +- The "Home" item is unnecessary for the project landing page. By convention the + upper-left logo links to the site landing page. +- The "Concepts" section is a brief introduction. Instead, it should contain a + complete technical overview that's accessible to a new user. - "Installing" does a good job of providing complete installation instructions -for all user roles. Some additional "road signs" would help to guide users to -the correct installation for their role, OS, and so on. + for all user roles. Some additional "road signs" would help to guide users to + the correct installation for their role, OS, and so on. - "Serving" and "Eventing" organize the instructional information by functional component, and by user role within the component. The alternative is to flip this and organize by user role first: @@ -161,7 +160,7 @@ the correct installation for their role, OS, and so on. - Serving - Developer Guide - Eventing - - Serviing + - Serving - Knative CLI - The title implies a dedicated Knative CLI. There are two Knative CLIs documented here, `kn` and `func`. As well, `kubectl` is the first CLI documented on the page. @@ -171,46 +170,46 @@ The reference to the repo-based documentation is OK, but why is the not documented here? Its installation is documented on the site; this seems inconsistent. -***Table of contents*** +**_Table of contents_** The table of contents (TOC) in the LHS is hard to navigate. Some issues: 1. The LHS contains only one technical documentation section at a time (see - previous comment about the banner menu). It's more usual for the LHS to - contain the entire TOC and to not change between pages (except for expanding - and collapsing headings). -2. The expand/collapse items in the TOC are navigational only; they do not - bring up information pages. This isn't uncommon, but it's tedious to navigate - multi-level topics. It's also less efficient than displaying the overview or - introduction with the top-level entry. -3. There are singleton sub-headings in the TOC. For example, see [Concepts > - Resources > Serving Resources > Revisions] - (https://knative.dev/development/concepts/serving-resources/revisions/). - Especially with the navigation-only expand/collapse items, these represent - extra mouse clicks for the user with no added benefit. -4. There are multiple entry points to the same documentation in the TOC. *And* - there are duplicate information sections. For example: - Installing > Install the Knative CLI sends you to the `Knative CLI` page. This - completely changes the left-hand TOC but the banner menu is not set up to - highlight `Knative CLI`, so are no cues as to where you were just teleported - (violating the [principle of least astonishment] - (https://en.wikipedia.org/wiki/Principle_of_least_astonishment)). - -***New user experience*** + previous comment about the banner menu). It's more usual for the LHS to + contain the entire TOC and to not change between pages (except for expanding + and collapsing headings). +2. The expand/collapse items in the TOC are navigational only; they do not + bring up information pages. This isn't uncommon, but it's tedious to + navigate multi-level topics. It's also less efficient than displaying the + overview or introduction with the top-level entry. +3. There are singleton sub-headings in the TOC. For example, see [Concepts > + Resources > Serving Resources > Revisions] + (https://knative.dev/development/concepts/serving-resources/revisions/). + Especially with the navigation-only expand/collapse items, these represent + extra mouse clicks for the user with no added benefit. +4. There are multiple entry points to the same documentation in the TOC. _And_ + there are duplicate information sections. For example: Installing > Install + the Knative CLI sends you to the `Knative CLI` page. This completely changes + the left-hand TOC but the banner menu is not set up to highlight + `Knative CLI`, so are no cues as to where you were just teleported + (violating the [principle of least astonishment] + (https://en.wikipedia.org/wiki/Principle_of_least_astonishment)). + +**_New user experience_** The blurb under "Need to know more?" on the landing page sounds like it's going -to an information resource; the button says "Explore Knative". Instead it -goes to the Quickstart tutorials. It sounds more like it should go to "Serving +to an information resource; the button says "Explore Knative". Instead it goes +to the Quickstart tutorials. It sounds more like it should go to "Serving Architecture". -***Graphics*** +**_Graphics_** In many places, large graphics are placed before any explanatory text. Also, many graphics, especially in the E2E tutorial (incidentally, "end-to-end" should be spelled out), provide no information but serve to distract, clutter, and take up valuable screen space. -***Headings and titles*** +**_Headings and titles_** Tasks are for the most part well named using appropriate verbs. @@ -221,9 +220,9 @@ Project Documentation. #### Information architecture -***Is there high level conceptual content?*** +**_Is there high level conceptual content?_** -The "Concepts" document at the top of the websiteis a brief introduction to two +The "Concepts" document at the top of the website is a brief introduction to two of the components of Knative. It does not introduce the overall architecture or explain how it works. @@ -232,7 +231,7 @@ throughout the website. The existing conceptual information seems to assume that you're already familiar with Kubernetes and with the problems that Knative is intended to solve. -***Is every product feature documented?*** +**_Is every product feature documented?_** The documentation seems a little behind being feature-complete, based on open Github issues requesting feature documentation. See for example issues @@ -242,52 +241,53 @@ Github issues requesting feature documentation. See for example issues Every component section (Eventing, Serving) is organized differently. This requires extra cognitive work from the readers. -***Does the documentation define all user roles (personas) for the product?*** +**_Does the documentation define all user roles (personas) for the product?_** The "Audiences information" in Community is a good description of user roles. This information is reflected in subsections of the "Eventing" and "Serving" sections in the division between Developer and Admin topics. -***Are there instructions (tasks, tutorials) documented for features?*** +**_Are there instructions (tasks, tutorials) documented for features?_** Tasks are documented for most features. -***Are there instructions for all major use cases for each user role?*** +**_Are there instructions for all major use cases for each user role?_** Tasks are covered for different user roles; it's unknown whether this coverage is complete. -***Are tasks organized by user role and use case?*** +**_Are tasks organized by user role and use case?_** The documentation is organized by the key components. Tasks for each component -seem to be present, but could be more clearly written and better labeleled. +seem to be present, but could be more clearly written and better labeled. -***Does instructional content demonstrate atomicity*** -Are individual tasks clearly named according to their goals? +**_Does instructional content demonstrate atomicity_** Are individual tasks +clearly named according to their goals? For the most part tasks seem separate and well named. -***Are tasks written as numbered step-by-step instructions?*** +**_Are tasks written as numbered step-by-step instructions?_** Tasks are broken down into steps. In most cases steps are not numbered. Some procedures have embedded subtasks. Numbering of tasks and subtasks is inconsistent. -***Are task descriptions in headings and the TOC described with a verb phrase?*** +**_Are task descriptions in headings and the TOC described with a verb +phrase?_** Most task headings accurately describe the task. -***Is the documentation free of features that lack task documentation?*** +**_Is the documentation free of features that lack task documentation?_** Task documentation seems to exist for key features. It is sometimes difficult to locate. -***Is the “happy path” — the most common use case — documented?*** +**_Is the “happy path” — the most common use case — documented?_** The "Happy Path" seems to be building and running a simple service using all three of the Knative components. This is documented in the "E2E" tutorial. -***Is there a clear escalation path for users needing more help?*** +**_Is there a clear escalation path for users needing more help?_** In general, Knative help and community support are strong throughout the documentation and repositories. Troubleshooting could provide clearer @@ -302,42 +302,41 @@ documentation. The troubleshooting steps are little more than command examples showing the non-exception case output. In some cases the output is cryptic and it's not clear what to do. -***If the product exposes an API, is there a complete reference?*** +**_If the product exposes an API, is there a complete reference?_** There is a reference for the Eventing API. It contains no explanatory or introductory text, and many descriptions of functions and fields are missing, rudimentary, or tautological. -***If the product has CLIs, are there complete references?*** +**_If the product has CLIs, are there complete references?_** There are references for the two CLIs, `kn` and `func`. The references are contained in their respective repos, not in the technical documentation. -***Is content up to date and accurate?*** +**_Is content up to date and accurate?_** The content seems up to date based on the versioning and release mechanisms. -***Does the doc separate conceptual, instructional, and reference info?*** +**_Does the doc separate conceptual, instructional, and reference info?_** Individual topics are separated by information type. - #### New user content -***Is “getting started” clearly labeled?** -(“Getting started”, “Installation”, “First steps”, or the equivalent.) +**\*Is “getting started” clearly labeled?** (“Getting started”, “Installation”, +“First steps”, or the equivalent.) -There is no clearly labeleld "Getting Started" page. There is a "Quickstart" +There is no clearly labeled "Getting Started" page. There is a "Quickstart" tutorial, with an accompanying plugin, that serves (primarily) as a beginner getting-started procedure. -***Is there a “getting started” path for all user roles?*** +**_Is there a “getting started” path for all user roles?_** -The "Quckstart" tutorial does not discuss roles. It acknowledges that the +The "Quickstart" tutorial does not discuss roles. It acknowledges that the exercise does a simplified local installation and directs the reader to YAML or Operator-based installs for production server installation. -***Is installation documented step-by-step?*** +**_Is installation documented step-by-step?_** Installation is thoroughly documented. Instructions are step-by-step and well organized. That said, I could not install using the Quickstart tutorial because @@ -346,107 +345,104 @@ Release Notes pages for binary downloads. This was confusing. Downloading the binary from the release page is not straightforward. The download links are under "Assets", far down the page. -***Are different types of installation documented if necessary?*** -(development, test, production) +**_Are different types of installation documented if necessary?_** (development, +test, production) The Quickstart tutorial documents a local install. Other (server) installs are documented in the Install section. -***If needed, are multiple OSes documented?*** +**_If needed, are multiple OSes documented?_** Installs for multiple OSes are documented implicitly (for example, the install binaries are characteristic of their respective OSes). A discussion of OSes up -front in the prereqs section would be appropriate. +front in the prerequisite section would be appropriate. -***Do users know where to go after reading the getting started guide?*** +**_Do users know where to go after reading the getting started guide?_** Next steps are documented at the end of the quickstart and some other sections. -***Is new user content clearly signposted on the site’s homepage?*** +**_Is new user content clearly signposted on the site’s homepage?_** There is no clearly labeled new user content available from the landing page. The closest is the Quickstart tutorial. -***Is there easily copy-pastable sample code or other example content?*** +**_Is there easily copy-paste sample code or other example content?_** There are code samples available in "Code samples", organized by Knative component. #### Content maintainability and site mechanics - -***Is your documentation searchable?*** +**_Is your documentation searchable?_** The documentation is searchable. The Search function does not truncate results. For example, the "Puppet" entry when searching "getting started" displays the page's entire 900 words. -***Are you planning for localization/internationalization?*** +**_Are you planning for localization/internationalization?_** -***Is a localization framework present?*** +**_Is a localization framework present?_** Apparently not. There is no evident localization or mechanism for localization. -***Do you have a clearly documented method for versioning your content?*** +**_Do you have a clearly documented method for versioning your content?_** Content is versioned up to the most recent release using branches in the knative/docs Github repo. The process is documented in the contribute-to-docs directory in the repo. The version drop-down contains the latest three releases plus pre-release. No older archived versions are offered on the site. -***Is release-specific information documented in release notes?*** +**_Is release-specific information documented in release notes?_** The repo contains appropriate release notes. -***Is the documentation free of duplicate sections of information?*** +**_Is the documentation free of duplicate sections of information?_** Duplicated information is present in the doc. It is deliberately included from a collection of reusable doc snippets. -***Do informational graphics add value by providing information?*** +**_Do informational graphics add value by providing information?_** Graphics are large and contain little new information, especially in the E2E tutorial. Some of the conceptual diagrams (component diagrams, flow charts) are helpful. -***Will graphics require modifications?*** -For example, due to software changes, GUI updates, or translation? +**_Will graphics require modifications?_** For example, due to software changes, +GUI updates, or translation? Graphics are unlikely to require frequent updates; for example, there are no screen shots. - #### Content creation processes -***Is there a clearly documented contribution process for documentation?*** +**_Is there a clearly documented contribution process for documentation?_** The documentation contribution process is well documented in the repo. -***Does the code release process include documentation creation & updates?*** +**_Does the code release process include documentation creation & updates?_** Documentation releases are controlled by the release process. The contribution process documents how to update previous versions of the documentation, if necessary. -***Who reviews and approves documentation pull requests?*** +**_Who reviews and approves documentation pull requests?_** -***Does the website have a clear owner/maintainer?*** +**_Does the website have a clear owner/maintainer?_** Review and approval of documentation releases is role-based and is controlled by the OWNERS and OWNER_ALIASES files in the repo. A steering committee is among the leadership identified in these files. - #### Inclusive language -***Are there customer-facing utilities, endpoints, class names, or features*** -that use non-recommended words as documented by the Inclusive Naming -Initiative website? +**_Are there customer-facing utilities, endpoints, class names, or features_** +that use non-recommended words as documented by the Inclusive Naming Initiative +website? The documentation contains few non-recommended words as documented by the [Inclusive Naming Initiative](https://inclusivenaming.org) website. -***Does the project use language like "simple", "easy", etc.?*** +**_Does the project use language like "simple", "easy", etc.?_** The Knative documentation avoids ableist language. The Knative style guide explicitly discourages language that assumes a level of understanding ("just", @@ -460,17 +456,17 @@ The simplest solution to untangling the documentation from the landing page is probably to: - Add a "Documentation" tab on the right alongside "Blog," "About," and -"Community" + "Community" - Move the tech docs items from the banner to the left-hand sidebar (LHS) Other suggestions: - Remove the "Home" item. - Write a comprehensive "Concepts" section using conceptual material from the -rest of the documentation. + rest of the documentation. - Rename "Tutorial" to "Tutorials". - Add navigational cues to the "Installation" section to better guide users to -the right instructions and downloads for their user role, OS, and use case. + the right instructions and downloads for their user role, OS, and use case. - Rename "Developer Topics" and "Admin Topics" to "Developer Tasks" and "Admin Tasks" to cue readers. These are effectively user guides and need to be recognizable as such by users. @@ -481,11 +477,10 @@ the right instructions and downloads for their user role, OS, and use case. - Rename "Knative CLI" to "CLI tools". Include the `kn` CLI documentation on the documentation site. - In "Reference": Rewrite at the top of the page: "This page describes Knative - security and disclosure information." - to - "This page describes how to validate code and report security vulnerabilites - in Knative. For a complete description of the Knative threat model, see the - [Knative security working group repo] + security and disclosure information." to "This page describes how to validate + code and report security vulnerabilities in Knative. For a complete + description of the Knative threat model, see the [Knative security working + group repo] (https://github.com/knative/community/blob/main/working-groups/security/threat-model.md)." Then change headings: "Verifying code signature" and "Reporting a vulnerability." @@ -496,11 +491,11 @@ the right instructions and downloads for their user role, OS, and use case. - Add a glossary in the Reference section. - Reevaluate each graphic on the site. Is it adding value? If not, eliminate it. Does it take up so much page space that it forces unnecessary scrolling? - Reduce the size. Especially in the E2E tutorial, get rid of the large graphics. - Their only purpose here is to cue the user to the type of task. Make them 32x32 - icons, or get rid of them. In the text, tell the user what the graphic is - before they see it, and make sure the picture is adding value, or else delete - it. + Reduce the size. Especially in the E2E tutorial, get rid of the large + graphics. Their only purpose here is to cue the user to the type of task. Make + them 32x32 icons, or get rid of them. In the text, tell the user what the + graphic is before they see it, and make sure the picture is adding value, or + else delete it. - Make TOC titles agree with page titles. Rename "About" in the banner to something more descriptive: "Why Knative?", "Testimonials and Case Studies", or "Endorsements". @@ -512,25 +507,25 @@ the right instructions and downloads for their user role, OS, and use case. - Spell out words to avoid abbreviations. For example: Replace "E2E" with "end to end". - #### Information architecture -***Conceptual overview*** +**_Conceptual overview_** Update the "Concepts" section to be a complete overview of the Knative system. Start with an explanation of Knative's purpose that's understandable to new -users and to readers who are only passingly familiar with containerized software. +users and to readers who are only passingly familiar with containerized +software. Include a complete explanation of Knative's components and how they're related. This is a good short explanation of the Knative components (though a little marketing-ish) that's on the CNCF website: - Knative is a developer-focused serverless application layer which is a great - complement to the existing Kubernetes application constructs. Knative consists - of three components: an HTTP-triggered autoscaling container runtime called - “Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called - “Knative Eventing”, and a developer-focused function framework which leverages - the Serving and Eventing components, called "Knative Functions". +Knative is a developer-focused serverless application layer which is a great +complement to the existing Kubernetes application constructs. Knative consists +of three components: an HTTP-triggered autoscaling container runtime called +“Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called +“Knative Eventing”, and a developer-focused function framework which leverages +the Serving and Eventing components, called "Knative Functions". None of the instructional material is going to make sense without an understanding of the Knative architecture. @@ -539,11 +534,10 @@ Some specifics: Rewrite: "The documentation in this section explains commonly referenced Knative concepts and abstractions, and helps to provide you with a better understanding -of how Knative works." -as -"This documentation explains what Knative is for and how it works." +of how Knative works." as "This documentation explains what Knative is for and +how it works." -***Escalation path*** +**_Escalation path_** Expand or eliminate the FAQ. My preference is to eliminate it. @@ -554,11 +548,11 @@ each command is intended to diagnose. Expand the Eventing API reference to include meaningful explanations of every field and function. Add a short introduction to the API reference. -***New user content*** +**_New user content_** Add a "Getting Started" page at the top level of the documentation. This page should map a reader's user role and goals to content that helps them install, -evaluate, or learn about the product, depending on their goal. For exmaple, +evaluate, or learn about the product, depending on their goal. For example, direct new users to the Quickstart tutorial, evaluators or potential buyers to the conceptual overview, and so on. @@ -568,7 +562,7 @@ downloads list. Move the install download links to the top of the Release Notes or clearly link to them from the top of the Release Notes. Or, put them on their own Downloads page. -***Content maintainability & site mechanics*** +**_Content maintainability & site mechanics_** Configure the Search to truncate results after 100 characters or so. Displaying the entire page text of each result hinders users' ability to find their result. @@ -582,7 +576,7 @@ Knative is a **graduated** project of CNCF. This means that the project should have [_very high_][criteria] standards for documentation. | Criterion | [Rating (1-5)] | -| ----------------------------------------- | -------------- | +| ----------------------------------------- | ------------------------------ | | Communication methods documented | 5 - Exemplary | | Beginner friendly issue backlog | 3 - Meets standards | | “New contributor” getting started content | 3 - Meets standards | @@ -590,16 +584,15 @@ have [_very high_][criteria] standards for documentation. ### Comments - #### Communication methods documented -***Is there a Slack/Discord or equivalent community linked from your website?*** +**_Is there a Slack/Discord or equivalent community linked from your website?_** -***Is there a direct link to your GitHub project or repository?*** +**_Is there a direct link to your GitHub project or repository?_** -***Can users find and join periodic project meetings, if applicable?*** +**_Can users find and join periodic project meetings, if applicable?_** -***Are mailing lists documented?*** +**_Are mailing lists documented?_** The site lists community resources that include: @@ -609,58 +602,54 @@ The site lists community resources that include: - A Stack Overflow topic - A Google Groups mailing list - #### Beginner friendly issue backlog -***Are docs issues well-triaged?*** +**_Are docs issues well-triaged?_** Doc issues are well triaged; there are tags classifying changes according to size and status. -***Is there a clearly marked way for new contributors to make contributions?*** +**_Is there a clearly marked way for new contributors to make contributions?_** (A “good first issue” label?) There is a "good first issue" label in the issues list. -***Are issues well-documented (i.e., more than just a title)?*** +**_Are issues well-documented (i.e., more than just a title)?_** Issue descriptions are uneven. Many issues are well documented, but some lack basic information. -***Are issues maintained for staleness?*** +**_Are issues maintained for staleness?_** There is a archiving bot for stale doc issues, but there are issues as old as four years in the repo. - #### New contributor getting started content -***Do you have a community repository or section on your website?*** +**_Do you have a community repository or section on your website?_** There is a separate [community repo](https://github.com/knative/community) in the Knative project. -***Is there a document welcoming new contributors?*** -And documenting a first contribution process? +**_Is there a document welcoming new contributors?_** And documenting a first +contribution process? There is ample documentation for contributors but no documentation specifically for new contributors. -***Can new users find where to get help?*** +**_Can new users find where to get help?_** There are ample resources for new users to get support from the community. - #### Project governance documentation -***Is project governance clearly documented?*** +**_Is project governance clearly documented?_** Project [governance](https://github.com/knative/community/blob/main/GOVERNANCE.md) is documented in the [community repo](https://github.com/knative/community) in the Knative project. - ### Recommendations No recommendations. @@ -699,10 +688,9 @@ have [_very high_][criteria] standards for documentation. ### Comments - #### Single-source requirement -The project website and documentaiton are contained in a single repo. +The project website and documentation are contained in a single repo. Every code repo in the project has its own `docs` folder. @@ -766,8 +754,8 @@ We evaluate on the following: - Is the brand used across the website consistently? - Is the website’s typography clean and well-suited for reading? -Footer: "Knative is a Cloud Native Computing Foundation incubation project". Should be "incubating". - +Footer: "Knative is a Cloud Native Computing Foundation incubation project". +Should be "incubating". #### Case studies/social proof diff --git a/analyses/0015-knative/issues.md b/analyses/0015-knative/issues.md index f7d5a71..9a314f1 100644 --- a/analyses/0015-knative/issues.md +++ b/analyses/0015-knative/issues.md @@ -6,18 +6,20 @@ modified: 2025-07-28 author: Dave Welsch (@dwelsch-esi) --- + + # Separate technical documentation from the project page ## Overview The Knative project [landing page] redirects to the doc page: -`https://knative.dev/docs/`. The project landing page contains all the -elements you'd expect on an open-source software page, including case studies, -user endorsements, and links to the community. +`https://knative.dev/docs/`. The project landing page contains all the elements +you'd expect on an open-source software page, including case studies, user +endorsements, and links to the community. It also includes the technical documentation in the banner menu. This arrangement conflates the project and the technical documentation, mixing -marketing and technical information. +marketing and technical information. It's helpful to users if there's a clear separation between technical documentation and other information. The technical documentation is goal-driven @@ -29,14 +31,12 @@ Audience: All Type: All - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -44,7 +44,6 @@ Related material in the current doc: - https://github.com/knative/ - https://github.com/knative/docs/ - Suggested changes: The simplest solution to untangling the documentation from the landing page is @@ -60,7 +59,6 @@ probably to: - Remove the version drop-down from the project landing page (and the other non-documentation project pages). - # Rename pages ## Overview @@ -91,7 +89,6 @@ Related material in the current doc: - https://knative.dev/docs/serving/ - https://knative.dev/docs/eventing/ - Suggested changes: - Remove "About" from titles: @@ -99,16 +96,15 @@ Suggested changes: - "About Eventing Features" > "Eventing Features" - and so on. - Rename "Tutorial" to "Tutorials" (there is more than one tutorial here). -- Make verb tense consistent in procedure titles. Use "-ing" verbs to title tasks - and processes (thiis is already done in the majority of cases!): +- Make verb tense consistent in procedure titles. Use "-ing" verbs to title + tasks and processes (this is already done in the majority of cases!): - [Configure Broker defaults] > "Configuring Broker defaults" - [Install Knative using quickstart] > "Installing Knative using quickstart" - and so on. -- In [Serving] and [Eventing], rename "Developer Topics" and - "Admin Topics" to "Developer Tasks" and "Admin Tasks" to cue readers. -- Retitle this page: - [Knative Eventing - The Event-driven application platform for Kubernetes] - to "Eventing". +- In [Serving] and [Eventing], rename "Developer Topics" and "Admin Topics" to + "Developer Tasks" and "Admin Tasks" to cue readers. +- Retitle this page: [Knative Eventing - The Event-driven application platform + for Kubernetes] to "Eventing". - Rename "Knative CLI" to "CLI tools". - Make TOC titles agree with page titles. Some examples (not a complete list): - Change "Install the Knative CLI" in the TOC to match the page title: @@ -117,8 +113,7 @@ Suggested changes: - Change "About Apache Kafka Broker" in the TOC to match the page title: [Knative Broker for Apache Kafka]. - Rename "About" in the landing page banner to something less misleading: "Why - Knative?", "Testimonials and Case Studies", or "Endorsements". - + Knative?", "Testimonials and Case Studies", or "Endorsements". # Update technical overview @@ -130,11 +125,11 @@ section is in the current documentation, but be much more comprehensive. This conceptual overview serves two purposes: 1. It helps potential users evaluate whether Knative is the right solution to -their problem; + their problem; 2. It provides all users with enough background information to understand the -instructional and reference material later in the documentation. User don't have -to read it all before proceeding, but they will refer to it when they don't -understand how the product's pieces fit together. + instructional and reference material later in the documentation. User don't + have to read it all before proceeding, but they will refer to it when they + don't understand how the product's pieces fit together. Audience: All @@ -156,26 +151,25 @@ Related material in the current doc: - https://knative.dev/docs/serving/request-flow/ - Almost any page currently titled "About (something)" - Suggested changes: Update the "Concepts" page to be a comprehensive conceptual overview of the -entire system. Start with an introduction that explains what the product is -and what problems it is designed to solve. This information should be accessible -to someone who is not an expert container developer or admin. If some background +entire system. Start with an introduction that explains what the product is and +what problems it is designed to solve. This information should be accessible to +someone who is not an expert container developer or admin. If some background knowledge is required to understand the concepts, state what that knowledge is. Follow with a description of the product architecture that explains its components and how they interoperate. From the CNCF website: - Knative is a developer-focused serverless application layer which is a great - complement to the existing Kubernetes application constructs. Knative consists - of three components: an HTTP-triggered autoscaling container runtime called - “Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called - “Knative Eventing”, and a developer-focused function framework which leverages - the Serving and Eventing components, called "Knative Functions". +Knative is a developer-focused serverless application layer which is a great +complement to the existing Kubernetes application constructs. Knative consists +of three components: an HTTP-triggered autoscaling container runtime called +“Knative Serving”, a CloudEvents-over-HTTP asynchronous routing layer called +“Knative Eventing”, and a developer-focused function framework which leverages +the Serving and Eventing components, called "Knative Functions". -Finally, explain essential but tangential topics like authenication and +Finally, explain essential but tangential topics like authentication and authorization, still at a conceptual level. # Update Installation to better orient users @@ -192,21 +186,18 @@ Audience: Admins and developers Type: Instructional - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://github.com/knative/install - Suggested changes: On the [Installing Knative] page, provide a roadmap at the top to direct users @@ -228,14 +219,12 @@ Audience: All Type: All - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -247,24 +236,23 @@ Related material in the current doc: Suggested changes: - In the [Eventing] section, move "Event Mesh" under "Concepts". -- Move the [Release Notes] to the top level of the TOC - (and change the URL to https://knative.dev/docs/relnotes/). +- Move the [Release Notes] to the top level of the TOC (and change the URL to + https://knative.dev/docs/relnotes/). - Make the "Explore Knative" button the landing page link to the conceptual - overview. Or, change the button label to "Quick Start". Its current label - is misleading. + overview. Or, change the button label to "Quick Start". Its current label is + misleading. - Remove the Eventing FAQ. It has only one entry, and that topic is covered - elsewhere in the documentation. + elsewhere in the documentation. - Are [Revisions] the only Knative Resource? Roll this menu up: - `Serving > Resources > Revisions > About Revisions` - to `Serving > Revisions > About Revisions`. + `Serving > Resources > Revisions > About Revisions` to + `Serving > Revisions > About Revisions`. # Document the kn CLI on the site ## Overview -The `kn` CLI documentation is maintained in the -[/knative/kn] repo, except for the install instrutions, which are on the doc -site. +The `kn` CLI documentation is maintained in the [/knative/kn] repo, except for +the install instructions, which are on the doc site. Consolidate the `kn` CLI documentation so that it's maintained in one place. @@ -272,33 +260,28 @@ Audience: Admin and developer Type: Reference - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://github.com/knative/ - Suggested changes: Document the `kn` CLI on the documentation website rather than linking to the -[/knative/kn] repo documentation. - +[/knative/kn] repo documentation. # Revise the Security and threat disclosure page ## Overview -The -[Knative Security and Disclosure Information] page has some misleading and +The [Knative Security and Disclosure Information] page has some misleading and confusing elements. Rewrite the introduction to this page so that it's clear what procedures and information are available. @@ -306,14 +289,12 @@ Audience: Admin Type: Instructional - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -325,15 +306,15 @@ Suggested changes: In [Reference]: Rewrite the introduction at the top of the page, including the bullet point link -to to the threat model, to: +to to the threat model, to: -"This page describes how to validate code and report security vulnerabilites in +"This page describes how to validate code and report security vulnerabilities in Knative. For a complete description of the Knative threat model, see the -[Knative security working group repo]." -Then change headings: "Verifying code signature" and "Reporting a vulnerability." +[Knative security working group repo]." Then change headings: "Verifying code +signature" and "Reporting a vulnerability." -Rename the heading "Code Signature Verification" to -"Verifying a code signature". +Rename the heading "Code Signature Verification" to "Verifying a code +signature". Rename the heading "Report a vulnerability" to "Reporting a vulnerability". @@ -351,21 +332,18 @@ Audience: All Type: Reference - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://github.com/knative/ - Suggested changes: Add a glossary to the reference section of the documentation. Include terms that @@ -380,14 +358,13 @@ refer to other glossary entries in the definition. Order the entries alphabetically. - # Review graphics ## Overview Graphics should enhance understanding by illustrating concepts and processes. Many graphics on the Knative site detract from, rather than enhance, the -usability of documentation. +usability of documentation. Review the graphics on the site to make sure they meet these criteria: @@ -406,14 +383,12 @@ Audience: All Type: Conceptual - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -429,7 +404,6 @@ Related material in the current doc: - https://knative.dev/docs/serving/request-flow/ - https://knative.dev/docs/serving/encryption/encryption-overview/ - Suggested changes: - Briefly introduce the system diagram in the [Concepts overview]. This can be a @@ -439,7 +413,6 @@ Suggested changes: - Similarly for other conceptual graphics on the site: Refer to them from the text. - # Edit for conformance to style guide ## Overview @@ -450,43 +423,41 @@ Audience: All Type: All - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://github.com/knative/ - Suggested changes: Specific Knative style rules that will have the biggest impact: -- *Use imperatives for headings of procedures.* Technical writing best practice - has traditionally been to use gerunds ("-ing" verbs), but this is okay as well. - More imporant is to be consistent. Use the same form for all procedure headings. -- *Use simple and direct language.* To the extent possible, follow the "Voice - and language" guidelines in the style guide. For example, there are 50 instances - of the word "please" in the Knative documentation. Remove these and use simple - imperative sentences for instructions. -- *Avoid statements that will soon be out of date.* This addresses - maintainability. See the [example] in the style guide. There are many instances - of the word "currently" in the Knative documentation. + +- _Use imperatives for headings of procedures._ Technical writing best practice + has traditionally been to use gerunds ("-ing" verbs), but this is okay as + well. More important is to be consistent. Use the same form for all procedure + headings. +- _Use simple and direct language._ To the extent possible, follow the "Voice + and language" guidelines in the style guide. For example, there are 50 + instances of the word "please" in the Knative documentation. Remove these and + use simple imperative sentences for instructions. +- _Avoid statements that will soon be out of date._ This addresses + maintainability. See the [example] in the style guide. There are many + instances of the word "currently" in the Knative documentation. - Spell out words to avoid abbreviations. For example: Replace "E2E" with "end to end". -- *Use simple and direct language.* For example, from [Concepts]: "The +- _Use simple and direct language._ For example, from [Concepts]: "The documentation in this section explains commonly referenced Knative concepts and abstractions, and helps to provide you with a better understanding of how Knative works" could be: "This documentation explains what Knative is for and how it works." - # Improve troubleshooting ## Overview @@ -500,14 +471,12 @@ Audience: All Type: Instructional - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -519,21 +488,19 @@ Related material in the current doc: - https://knative.dev/docs/bookstore/page-1/send-review-comment-to-broker/#step-2-create-broker - https://knative.dev/docs/bookstore/page-2/sentiment-analysis-service-for-bookstore-reviews/#prerequisite-1-install-knative-func-cli - Suggested changes: Two possible approaches: 1. Expand each troubleshooting step to explain what the step is trying to - diagnose. (Many of the current troubleshooting steps are no more than "use this - command to diagnose ..."). Make sure that there are links to each step from the - procedure where the issue can be encountered. + diagnose. (Many of the current troubleshooting steps are no more than "use + this command to diagnose ..."). Make sure that there are links to each step + from the procedure where the issue can be encountered. 2. Consolidate all the troubleshooting procedures to a single troubleshooting - guide, organized by component. Again, provide links to the relevant points in - the guide from each procedure. - Exception: The end-to-end tutorial example has a lot of troubleshooting - information. As is the case currently, it should have its own troubleshooting - guide or guides. + guide, organized by component. Again, provide links to the relevant points in + the guide from each procedure. Exception: The end-to-end tutorial example has + a lot of troubleshooting information. As is the case currently, it should + have its own troubleshooting guide or guides. # Fill out the Eventing API @@ -554,14 +521,12 @@ This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: - https://knative.dev/docs/eventing/reference/eventing-api/ - Suggested changes: Add a brief introduction to the Eventing API, explaining what the API is for, @@ -580,8 +545,8 @@ more information: "Retry after an exponentially increasing number of seconds (1, # Write a Getting Started page The Quickstart tutorial is useful, but it doesn't fully orient new users. A -getting started page would help, with meta information about what to expect -and where to go on the documentation site. +getting started page would help, with meta information about what to expect and +where to go on the documentation site. ## Overview @@ -589,14 +554,12 @@ Audience: New users Type: Instructional - ## Context This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -608,22 +571,22 @@ Suggested changes: Add a "Getting Started" page at the top level of the documentation. This page should map a reader's user role and goals to content that helps them install, -evaluate, or learn about the product, depending on their goal. For exmaple, +evaluate, or learn about the product, depending on their goal. For example, direct new users to the Quickstart tutorial, evaluators or potential buyers to -the conceptual overview, and so on. +the conceptual overview, and so on. See, for example, getting started pages for: - [Kubernetes] -- [The Update Framework] - (a little unusual because it's a specification, not a software product) +- [The Update Framework] (a little unusual because it's a specification, not a + software product) - [Python] (a kitchen-sink approach, to be sure) # Make install downloads findable Currently the binary install download links in the Installing section redirect to the release notes, where the list of download files is far down the page. -Move and relabel the download file sectionm so that the files are easy to find. +Move and relabel the download file section so that the files are easy to find. ## Overview @@ -637,7 +600,6 @@ This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -677,7 +639,6 @@ This issue tracks recommended changes resulting from an analysis of the Knative documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/analyses under `0015-knative`. - ## Possible Implementation Related material in the current doc: @@ -694,28 +655,35 @@ so. This change probably has to be implemented in the `mkdocs` configuration. I'd start by looking at the [mkdocs config file]. - [/knative/kn]: https://github.com/knative/client [Concepts]: https://knative.dev/docs/concepts/ [Concepts overview]: https://knative.dev/docs/concepts/ -[Configure Broker defaults]: https://knative.dev/docs/eventing/configuration/broker-configuration/ +[Configure Broker defaults]: + https://knative.dev/docs/eventing/configuration/broker-configuration/ [Eventing]: https://knative.dev/docs/eventing/ -[example]: https://github.com/knative/docs/blob/main/contribute-to-docs/style-guide/voice-and-language.md#avoid-statements-that-will-soon-be-out-of-date -[Install Knative using quickstart]: https://knative.dev/docs/install/quickstart-install/ +[example]: + https://github.com/knative/docs/blob/main/contribute-to-docs/style-guide/voice-and-language.md#avoid-statements-that-will-soon-be-out-of-date +[Install Knative using quickstart]: + https://knative.dev/docs/install/quickstart-install/ [Installing Knative]: https://github.com/knative/install [Installing the Knative CLI]: https://knative.dev/docs/client/install-kn/ -[Knative Broker for Apache Kafka]: https://knative.dev/docs/eventing/brokers/broker-types/kafka-broker/ -[Knative Eventing - The Event-driven application platform for Kubernetes]: https://knative.dev/docs/eventing/ -[Knative Security and Disclosure Information]: https://knative.dev/docs/reference/security/ -[Knative security working group repo]: https://github.com/knative/community/blob/main/working-groups/security/threat-model.md -[Knative style guide]: https://github.com/knative/docs/tree/main/contribute-to-docs/style-guide +[Knative Broker for Apache Kafka]: + https://knative.dev/docs/eventing/brokers/broker-types/kafka-broker/ +[Knative Eventing - The Event-driven application platform for Kubernetes]: + https://knative.dev/docs/eventing/ +[Knative Security and Disclosure Information]: + https://knative.dev/docs/reference/security/ +[Knative security working group repo]: + https://github.com/knative/community/blob/main/working-groups/security/threat-model.md +[Knative style guide]: + https://github.com/knative/docs/tree/main/contribute-to-docs/style-guide [Kubernetes]: https://kubernetes.io/docs/setup/ [landing page]: https://knative.dev/ [Metrics]: https://knative.dev/docs/serving/autoscaling/autoscaling-metrics/ [mkdocs config file]: https://github.com/knative/docs/blob/main/mkdocs.yml [Python]: https://wiki.python.org/moin/BeginnersGuide [Reference]: https://knative.dev/docs/reference/ -[Release Notes]: https://knative.dev/docs/reference/relnotes/ +[Release Notes]: https://knative.dev/docs/reference/relnotes/ [Revisions]: https://knative.dev/docs/serving/revisions/ [Serving]: https://knative.dev/docs/serving/ [The Update Framework]: https://theupdateframework.io/docs/getting-started/ diff --git a/docs/analytics/ua-to-ga4.md b/docs/analytics/ua-to-ga4.md index 3855f90..3cb8336 100644 --- a/docs/analytics/ua-to-ga4.md +++ b/docs/analytics/ua-to-ga4.md @@ -30,7 +30,6 @@ In preparation for the migration, follow these steps: issues opened for the pilot projects listed in #108. 2. Determine which **analytics library** your project's website is using. - - Visit your project's website. - View the page source of any website page. - Search for "`https://www.google`". Look at all instances. @@ -69,7 +68,6 @@ Follow these steps: [analytics.google.com](https://analytics.google.com). 3. **Create a GA4 site tag**: - - Select **Admin** (bottom of left-nav) - Select **GA4 Setup Assistant** - Select **Get started** under **I want to create a new Google Analytics 4 @@ -82,7 +80,6 @@ Follow these steps: 4. **Open the analytics console onto your GA4 site tag** and copy the measurement ID. Continuing from the previous step: - - Select **Go to your GA4 property** from the **GA4 Setup Assistant** view of your UA property.
This will open an analytics console onto your GA4 site tag. Perform the remaining steps from your GA4 console. @@ -92,7 +89,6 @@ Follow these steps: the appropriate row of the [status table][]. 5. Rename your UA property by adding the `- UA` suffix. From the UA console: - - Select **Admin** (bottom of left-nav) - Select **Property Settings** - Change the property name (which usually matches the project name), by @@ -104,14 +100,12 @@ Follow these steps: since the GA4 setup assistant will then have automatically [connected][] your GA4 site tag from your UA config. If you aren't sure, then you can check as follows: - - **Open** the analytics console for the **UA site tag** - Under **Admin** > **GA4 Setup Assistant**, look for your GA4 property in the **Connected Property** table. If you can't find your GA4 property, then you'll have to manually add it as follows: - - 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 @@ -138,7 +132,6 @@ analytics library. this will depend, in particular, on your project's site generator and setup. Here are some guidelines on how to switch over to `gtag.js`: - - [Docusaurus][]: - v1: add a `gtag: true` site configuration parameter. - v2: enable the gtag plugin. @@ -153,7 +146,6 @@ analytics library. 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: - - [Docusaurus][]: - v1: set the `gaTrackingId` site configuration parameter to your project's GA4 measurement ID. diff --git a/docs/website-guidelines-checklist.md b/docs/website-guidelines-checklist.md index 539c367..f4ba814 100644 --- a/docs/website-guidelines-checklist.md +++ b/docs/website-guidelines-checklist.md @@ -47,8 +47,8 @@ all projects following text: "The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see [Trademark Usage][]". - If your project has been converted to the Series LLC model (starting in - 2025), use the following **copyright statement**: "Copyright © - $PROJECT_NAME a Series of LF Projects, LLC." + 2025), use the following **copyright statement**: "Copyright © $PROJECT_NAME + a Series of LF Projects, LLC." ## Community and license files