From 75cc9b0b96a0ebe197b04aaa87f0a5d18bdb2e2e Mon Sep 17 00:00:00 2001 From: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> Date: Tue, 2 Jul 2024 10:05:49 +0900 Subject: [PATCH 1/5] Initialize the Japanese Localization Guidelines (#259) * feat: initialize Japanese l10n guide Signed-off-by: Junya Okabe * update: add review section Signed-off-by: Junya Okabe * fix: anchor link Signed-off-by: Junya Okabe * Update: l10n reviewer Signed-off-by: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> Signed-off-by: Junya Okabe * fix: linter errors Signed-off-by: Junya Okabe * feat: add ## Localization READMEs Signed-off-by: Junya Okabe * fix: link checker error Signed-off-by: Junya Okabe * update: .prettierignore Signed-off-by: Junya Okabe * Update docs/localization/README.md Co-authored-by: Patrice Chalin Signed-off-by: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> * Update .prettierignore Co-authored-by: Patrice Chalin Signed-off-by: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> * fix: L6 Signed-off-by: Junya Okabe --------- Signed-off-by: Junya Okabe Signed-off-by: Junya Okabe <86868255+Okabe-Junya@users.noreply.github.com> Co-authored-by: Patrice Chalin --- .prettierignore | 2 +- docs/localization/README.md | 4 ++ docs/localization/ja/README.md | 73 ++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 docs/localization/ja/README.md diff --git a/.prettierignore b/.prettierignore index ec634b6..f238ae8 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1 +1 @@ -# Nothing to ignore at the moment. +/docs/localization/ja diff --git a/docs/localization/README.md b/docs/localization/README.md index aae60c1..9ca8025 100644 --- a/docs/localization/README.md +++ b/docs/localization/README.md @@ -11,3 +11,7 @@ Every guide here must meet the following requirements: - Meets the requirements of the original open-source license. Guides here must not violate copyright or licensing requirements. + +## Localizations + +- [Japanese](ja/README.md) diff --git a/docs/localization/ja/README.md b/docs/localization/ja/README.md new file mode 100644 index 0000000..265ff8b --- /dev/null +++ b/docs/localization/ja/README.md @@ -0,0 +1,73 @@ +# CNCF日本語ローカライゼーション向けガイドライン + +このドキュメントでは、CNCFのプロジェクトをローカライズする際に参考になる一般的なガイドラインを提供します。 + +> [!IMPORTANT] +> 各プロジェクトに対してこのガイドラインをどの程度適用するかは、各プロジェクトのローカライゼーションリードが決定します。疑問点がある場合は、各プロジェクトの日本語ローカライゼーションリードやレビュアーと相談してください。 + +## 目次 + +- [スタイルガイド](#スタイルガイド) +- [固有の用語](#固有の用語) + - [例](#例) +- [レビュー](#レビュー) +- [プロジェクト](#プロジェクト) +- [コミュニケーション](#コミュニケーション) + +## スタイルガイド + +Kubernetesの[日本語ローカライゼーション向けのスタイルガイド](https://kubernetes.io/ja/docs/contribute/localization/#style-guide)に準拠してください。 + +## 固有の用語 + +CNCFのプロジェクト特有の用語については、原則として英語のまま表記してください。ただしこれらの用語や概念を説明をするページなどで日本語の訳語が必要な場合は、以下の表を参考にしてください。 + +| 英語 | 日本語 | +| --- | --- | +| Charter | チャーター | +| Governing Board | 運営委員会 | +| SIG (Special Interest Group) | Special Interest Group | +| TAB (Technical Advisory Board) | 技術諮問評議会 | +| TAG (Technical Advisory Group) | 技術諮問グループ | +| TOC (Technical Oversight Committee) | 技術監督委員会 | +| WG (Working Group) | ワーキンググループ | + +また次の表に示す用語はCNCF特有ではありませんが、表記を統一するため、原則として以下の表を参考にしてください。 + +| 英語 | 日本語 | +| --- | --- | +| Committee | 委員会 | +| White Paper | ホワイトペーパー | + +### 例 + +| 推奨 | 非推奨 | +| --- | --- | +| Platform WG | プラットフォームWG | +| Platform WG | プラットフォームワーキンググループ | +| SIG Docs | SIGドキュメント | +| TAG Runtime | TAGランタイム | + +## レビュー + +ローカライゼーションのPRを作成した際は、ローカライゼーションレビュアーにレビューを依頼してください。各リポジトリのレビュアーは、[プロジェクト](#プロジェクト)の表を参考にしてください。 +2人以上のローカライゼーションレビュアーからの承認を得ることを推奨します。 + +ローカライゼーションレビュアーからの承認を得た後、各リポジトリのメンテナーにPRのマージを依頼してください。 + +## プロジェクト + +すでにローカライゼーションが進められているプロジェクトの一覧です。ローカライゼーションPRを作成する際には、以下の表を参考にして、適宜ローカライゼーションリードやレビュアーに通知してください。 + +| プロジェクト | ローカライゼーションリード | ローカライゼーションレビュアー | +| --- | --- | --- | +| [CNCF Glossary](https://github.com/cncf/glossary) | [@naonishijima](https://github.com/naonishijima) | [@naonishijima](https://github.com/naonishijima), [@kaitoii11](https://github.com/kaitoii11), [@Okabe-Junya](https://github.com/Okabe-Junya) | +| [CNCF TAG App Delivery](https://github.com/cncf/tag-app-delivery) | [@hhiroshell](https://github.com/hhiroshell) | [@hhiroshell](https://github.com/hhiroshell), [@kaitoii11](https://github.com/kaitoii11), [@naonishijima](https://github.com/naonishijima) | +| [CNCF TAG Environmental Sustainability](https://github.com/cncf/tag-env-sustainability) | [@naonishijima](https://github.com/naonishijima) | [@naonishijima](https://github.com/naonishijima), [@kaitoii11](https://github.com/kaitoii11), [@Okabe-Junya](https://github.com/Okabe-Junya) | +| [CNCF TAG Runtime](https://github.com/cncf/tag-runtime) | [@kaitoii11](https://github.com/kaitoii11) | [@kaitoii11](https://github.com/kaitoii11), [@kenta-iijima](https://github.com/kenta-iijima), [@Okabe-Junya](https://github.com/Okabe-Junya) | + +## コミュニケーション + +CNCFのプロジェクトのローカライゼーションに関するコミュニケーションは、主に、[CNCFのSlack](https://cloud-native.slack.com)の[`#glossary-localization-japanese`](https://cloud-native.slack.com/archives/C057F81GFUG)チャンネルで行われています。ローカライゼーションに関する質問や提案がある場合は、こちらのチャンネルで議論してください。 + +CNCFのSlackに参加していない場合は、[Community Inviterのサイト](https://communityinviter.com/apps/cloud-native/cncf)から参加できます。 From d144317fb6358368ead22f8859d696de29229f08 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 29 Jul 2024 17:52:20 -0400 Subject: [PATCH 2/5] Fix broken link from Keda analysis (#268) Signed-off-by: Patrice Chalin --- analyses/0011-keda/keda-implementation.md | 2 +- analyses/0011-keda/keda-issues.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index 7508886..a57b89a 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -137,7 +137,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [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/) + - [FAQ](https://keda.sh/docs/latest/faq/) - Glossary - [Scalers](https://keda.sh/docs/2.13/scalers/) - [ActiveMQ](https://keda.sh/docs/2.13/scalers/activemq/) diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index 2d3bb63..e8d1f50 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -180,7 +180,7 @@ or provide a starting point. - [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/) + - [FAQ](https://keda.sh/docs/latest/faq/) - Glossary # Separate reference and task information From 3959be809c741cd883e789d3d7d521f69d6bbb90 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Tue, 30 Jul 2024 11:58:51 -0700 Subject: [PATCH 3/5] Criteria: sandbox update/clarification (#266) * Update README.md Corrected with new directory structure. Reorganized description. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Updated sandbox website assessment requirement. Miscellaneous small corrections. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update README.md Fix formatting errors, primarily line legth/LINT. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Fix MD linter and line-length errors. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update README.md Trailing spaces? Really? Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update criteria.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update keda-implementation.md Fixed faq link Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update keda-issues.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * fixing formatting issues brought up by prettier Signed-off-by: Nate W * Update docs/analysis/criteria.md Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Nate W * Update assistance.md Added a note to address program differences for projects at the Sandbox maturity level. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update assistance.md Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> --------- Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Nate W Co-authored-by: Nate W --- README.md | 62 +++++++++++------------ analyses/0011-keda/keda-implementation.md | 2 +- analyses/0011-keda/keda-issues.md | 2 +- docs/analysis/criteria.md | 50 ++++++++++-------- docs/assistance.md | 13 +++-- 5 files changed, 72 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index b19c2bf..be0b70e 100644 --- a/README.md +++ b/README.md @@ -3,35 +3,24 @@ 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. +- `docs` contains collected resources for building websites and developing + documentation, including recommended tools and practices, how-tos, and + evaluation checklists. Included are specific guidelines for: + - Setting up and maintaining a documentation website. + - Writing technical documentation for a project. + - Getting assistance from the CNCF TechDocs community. + - Analyzing project documentation, for use by CNCF TechDocs staff (in + `docs/analysis`). +- `analyses` (not to be confused with `docs/analysis`) contains all the + completed documentation analyses. -## 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 | - - - - -Various consultants and volunteers also contribute to CNCF Tech Docs projects. +## TechDocs Q&A -## Office hours +The CNCF tech docs team holds a Zoom call to answer questions and discuss +anything to do with documentation. Calls are held on the [fourth Wednesday of +every month at 8am Pacific time][date-time]. -The CNCF tech docs team holds office hours on the [fourth Wednesday of every -month at 8am Pacific time][date-time]. - -Office hours started on 30 September 2020. +TechDocs Q&A (formerly called _Office Hours_) started on 30 September 2020. ### Meeting link @@ -44,15 +33,26 @@ We store ongoing meeting notes in a ## Assistance program for technical documentation -The TechDocs team can assist CNCF projects analyze and improve their +The TechDocs team can help CNCF projects analyze and improve their documentation. For details, see the TechDocs [assistance program](docs/assistance.md). -### Resources +## 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 | + + + -The `docs/` directory contains collected resources for building websites and -developing documentation, including recommended tools and practices, how-tos, -and evaluation checklists. +Various consultants and volunteers also contribute to CNCF Tech Docs projects. [date-time]: https://tockify.com/cncf.public.events/monthly?search=CNCF%20Tech%20Writers%20Office%20Hours diff --git a/analyses/0011-keda/keda-implementation.md b/analyses/0011-keda/keda-implementation.md index a57b89a..a759b48 100644 --- a/analyses/0011-keda/keda-implementation.md +++ b/analyses/0011-keda/keda-implementation.md @@ -137,7 +137,7 @@ Here is a proposed outline for the tech doc Table of Contents: - [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/latest/faq/) + - [FAQ](https://keda.sh/docs/2.13/reference/faq/) - Glossary - [Scalers](https://keda.sh/docs/2.13/scalers/) - [ActiveMQ](https://keda.sh/docs/2.13/scalers/activemq/) diff --git a/analyses/0011-keda/keda-issues.md b/analyses/0011-keda/keda-issues.md index e8d1f50..c46e690 100644 --- a/analyses/0011-keda/keda-issues.md +++ b/analyses/0011-keda/keda-issues.md @@ -180,7 +180,7 @@ or provide a starting point. - [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/latest/faq/) + - [FAQ](https://keda.sh/docs/2.13/reference/faq/) - Glossary # Separate reference and task information diff --git a/docs/analysis/criteria.md b/docs/analysis/criteria.md index c0c9e61..e6719fb 100644 --- a/docs/analysis/criteria.md +++ b/docs/analysis/criteria.md @@ -21,7 +21,7 @@ documentation. We evaluate on the following: - If the product exposes an API, is there a complete reference? - Is content up to date and accurate? -Examples: +Example: - @@ -39,7 +39,10 @@ specifically for them. We evaluate on the following: top of your information architecture? - Is there easily copy-pastable sample code or other example content? -Examples: + + + +Example: - @@ -55,7 +58,7 @@ We evaluate on the following: directory structure? Is a localization framework present? - Do you have a clearly documented method for versioning your content? -Examples: +Example: - @@ -105,7 +108,7 @@ We evaluate on the following: join those meetings? - Are mailing lists documented? -Examples: +Example: - @@ -119,7 +122,7 @@ We evaluate on the following: - Are issues well-documented (i.e., more than just a title)? - Are issues maintained for staleness? -Examples: +Example: - (all of open tracing’s backlogs are well maintained!) @@ -136,7 +139,7 @@ We evaluate on the following: - Is there a document specifically for new contributors/your first contribution? - Do new users know where to get help? -Examples: +Example: - @@ -148,9 +151,9 @@ We evaluate on the following: - Is project governance clearly documented? -Examples: +Example: -- Any graduated CNCF project +- ## Website @@ -181,16 +184,20 @@ maturity levels so, for example, incubating projects must satisfy the requirements for sandbox projects. - **Sandbox** - - [Website guidelines](../website-guidelines-checklist.md): majority of the + - [Website guidelines](../website-guidelines-checklist.md): a 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 this maturity level to link out to documentation that hasn't yet been integrated into the website - - _Example_: website with a single homepage, without any documentation or, as - was mentioned above, linking out to an external (preexisting) source for - docs + - _Example_: website with a single homepage, without any documentation or, + as was mentioned above, linking out to an external (preexisting) source + for docs + - _However_: consider reading the recommended practices in this repository + and implementing as many of the best practices as you can. This groundwork + will pay big dividends later when you need to upgrade your practices and + update your documentation as an incubating project. Assistance is + available from CNCF TechDocs anytime, including answers to individual + questions or a documentation workshop. - **Incubating** - [Website guidelines][]: all guidelines are satisfied. - [Docs assessment][]: request an (re-)assessment through the CNCF [service @@ -207,7 +214,7 @@ requirements for sandbox projects. - The website repo is in an [archived state][] - The archived status of the project must be obvious to those visiting the website, such as through the use of a prominent banner. - - If a successor project exists, link to it's website and/or migration + - If a successor project exists, link to its website and/or migration documentation. [archived state]: @@ -254,9 +261,9 @@ We evaluate on the following: - 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 website’s typography clean and legible? -Examples: +Example: - @@ -282,9 +289,10 @@ Examples: ### SEO, Analytics and site-local search -SEO helps users find your project and it's documentation, and analytics helps -you monitor site traffic and diagnose issues like page 404s. Intra-site search, -while optional, can offer your readers a site-focused search results. +SEO helps users find your project and its documentation, and analytics helps you +monitor site traffic and diagnose issues like page 404s. Intra-site search, +while optional, offers your readers site-focused search results and is strongly +recommended. We evaluate on the following: @@ -313,7 +321,7 @@ We evaluate on the following: - Are site build times reasonable? - Do site maintainers have adequate permissions? -Examples: +Example: - diff --git a/docs/assistance.md b/docs/assistance.md index a322e87..5362657 100644 --- a/docs/assistance.md +++ b/docs/assistance.md @@ -1,9 +1,9 @@ # 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: +Documentation Assistance Program (the Program), a service offered by CNCF +TechDocs 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 @@ -18,6 +18,13 @@ process is designed to: 1. Leave the project team with an improved understanding and skill base for improving and maintaining the project documentation. +**Note**: The Program focuses on established projects at the _incubating_ and +_graduated_ maturity levels. The Program offers help for _sandbox_ projects as +well, but with less emphasis on analyzing existing documentation and more on +establishing good practices and starting a minimally viable documentation set. +For more information contact the +[CNCF TechDocs team](https://servicedesk.cncf.io/). + ## Phase 0: Training Some level of familiarity with the technical documentation process is required From 167a9e3441e756d5fe186d8c7d3d524474590cc3 Mon Sep 17 00:00:00 2001 From: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Date: Wed, 7 Aug 2024 16:06:12 -0700 Subject: [PATCH 4/5] Sandbox process (#269) * Added sandbox doc primer sandbox-doc-primer.md defines terms and outlines a process for getting started with project documentation in CNCF. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * fixing formatting Signed-off-by: Nate W * Update sandbox-doc-primer.md - Added release notes as an example of reference doc - Added links to more resources - Minor edits Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update sandbox-doc-primer.md Fixed format issue? Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * Update sandbox-doc-primer.md Added info about CNCF hosting project websites. Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> * fixing formatting Signed-off-by: Nate W --------- Signed-off-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Signed-off-by: Nate W Co-authored-by: Nate W --- docs/sandbox-doc-primer.md | 225 +++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 docs/sandbox-doc-primer.md diff --git a/docs/sandbox-doc-primer.md b/docs/sandbox-doc-primer.md new file mode 100644 index 0000000..43c6a63 --- /dev/null +++ b/docs/sandbox-doc-primer.md @@ -0,0 +1,225 @@ +# CNCF sandbox project documentation primer + +This document is a quick primer for CNCF project maintainers and contributors +who need to document their projects but don't know where to start. It provides a +framework for thinking about user documentation that will enable the project +contributors to write effective documentation from the very beginning and to get +the most out of documentation efforts as the project matures. + +## What is "good" documentation? + +Documentation quality is ultimately measured by how _effective_ it is. + +The purpose of documentation is to help the user of a product achieve their +objectives. The scope of these objectives ranges from individual tasks (use a +command correctly, connect to a database) to large-scale goals (write a software +product or module; configure a server farm). Objectives also vary by +[user role](#product-users) (new developer; software architect; IT +administrator). + +Documentation effectiveness, therefore, is defined by _how well it enables a +user to succeed in achieving their objectives_, within every range of scope and +for all users. + +### An information model for user documentation + +This discussion uses the following +[model](https://www.lios.ca/en/blogue/concept-task-reference/) to categorize +types of technical documentation. + +A documentation topic is one of these three types, depending on its purpose: + +- _Conceptual_ information describes one or more aspects of the project or its + products: its structure, purpose, motivation, architecture – almost anything. + Examples include: + - architectural overviews + - product histories + - technical white papers + - design discussions +- _Task-based_ information describes how to do something. Examples include: + - procedure documentation, from individual task instructions to full + instruction manuals + - code "recipes" for creating particular software components + - specialized instructions such as troubleshooting guides + - learning materials such as tutorials +- _Reference_ information is the "lookup" material specific to a product. + Examples include: + - API specifications + - command references + - knowledge bases + - user interface references + - error code lookups + - glossaries + - release notes + +### Descriptive vs. instructional documentation + +No type of information is "better" than any other. All three types are necessary +to good technical documentation and should be present in the docs for any +software product. + +That said, however, documentation writers involved with product development tend +to write _descriptive_ documentation: they emphasize conceptual and reference +information at the expense of task-based information. + +It's important, especially when developing a product, to describe what the +product is designed to do. But in general, this does not make good user +documentation. Descriptive documentation forces the user to search the +documentation for a combination of features that will accomplish their goal, +rather than being able to pursue that goal directly. + +Good software documentation is primarily _instructional_. The core of the +documentation set aims to help users efficiently accomplish their goals. A +traditional documentation set might contain a _getting started guide_ to help +the user set up their workspace; _tutorials_ to teach skills and techniques; a +_user guide_ (or _developer guide_) to explain and illustrate tools and +workflows; and a _reference guide_ (often built into an IDE) to look up APIs, +commands, or other toolkit components. + +Of course it's important that the documentation be feature-complete – that every +capability of the product be documented. But it's equally important that every +task that a user would reasonably want to perform be documented. A good cookbook +doesn't just list ingredients, it tells you how to use them. + +## A process for developing user documentation + +So if starting with design documentation and expanding on the product's +functionality isn't the best way to write user documentation, what is? + +Answer: To develop effective documentation it is necessary to describe the +product's users and their objectives. This might seem like unnecessary extra +work, but it will pay off very quickly in documentation quality. + +The rest of this document is a very brief description of a system for writing +effective documentation for all of a product's users. + +### Product users + +First, define your product's _user roles_. A user role (also called a +_persona_), is a type of user with a particular set of tasks they need to +perform. + +As an example, consider a hypothetical product that consists of a REST API +frontend to a server-based relational database. The user roles are: + +- _Developer_: Uses the REST API to list data records and perform CRUD + operations on the database. +- _Administrator_: Sets up and maintains the product on one or more servers, + including a production server. + +For any OSS project, there are also these roles: + +- _Contributor_: A member of the project community who contributes code or other + labor to the project itself. +- _Evaluator_: Someone who is considering using the product and needs to find + out more about it. + +One person can have multiple roles. For example, a contributor is often also a +user (developer or admin, in this case). + +### Write goals + +Next, determine the goals of each user role that are served by the product. For +the developer in the database example, a goal is probably to integrate the +database into an end-user application. + +For the admin, a goal is to set up, say, a production and a test server and to +populate them with identical data. + +### Develop tasks + +Analyze larger goals down to smaller ones. Ultimately, you want to get to the +most basic unit of task-based documentation: discrete step-by-step tasks. + +#### Write for new users + +Pay special attention to the goals of new users. + +For example, new-user goals for developers always include: + +- Installing dependencies and software +- Configuring a development environment +- Running a "hello world" example or a similar simple task to verify the product + +When writing for new users (or indeed, any user who isn't part of the +contributor community), try not to assume that the user knows anything about the +product. This is especially true when writing task documentation. + +In the database example, say that configuring the server consists of copying the +config file template to the config directory, setting permissions on the file, +and editing the file to include the server IPs and some other parameters. Time +and again we've seen configuration documentation that consists only of which +config parameters to set. An effective configuration task, though, would walk +through these steps: + +1. Copy the template from folder X to folder Y. +1. Name the file Z. +1. Set permissions on the file to ABC. +1. Edit the file to set parameters Q, R, S and T. (And include a link to the + config reference\!) + +Don't worry about giving too much information. Novice users need it, and expert +users will ignore it. + +### Support the task documentation + +Finally, support the task documentation with conceptual and reference +documentation. The developer, for example, will need a complete reference for +the REST API. The admin will need a complete description of every server +configuration option. Both will need a reference for the CLI, if there is one. + +Conceptual information should always include a technical overview. This includes +the product's purpose, architecture, and design rationales. This helps +prospective users decide whether it's a solution for their problem, and helps +advanced users reason about how to use or even extend its advanced features. + +## Nuts and bolts: deliverables and infrastructure + +### Required documentation + +A minimal documentation set varies by product, but some documents are (almost) +always required to make the product usable: + +- A technical overview +- A getting started guide +- Reference manual(s) + +[Here's more](https://expertsupport.com/library/quick-and-easy-document-specifications/) +on how to determine which docs you really need. + +### Where to put it + +At the sandbox stage, making the documentation available in some form is more +important than hosting it in any particular place. That said, CNCF TechDocs has +a [number of resources](https://github.com/cncf/techdocs/tree/main/docs) for +creating web-based documentation. + +CNCF TechDocs can purchase, set up, and maintain your website's domain at no +cost to your project. Contact CNCF TechDocs through the +[CNCF TechDocs Service Desk](https://servicedesk.cncf.io) to request website +hosting. + +Even if you don't use the CNCF recommended tools, it's worth reading the +recommendations to preview the sorts of issues you'll encounter as the +documentation matures. These issues parallel those facing the code +infrastructure, and include things like scaling, hosting, versioning, indexing, +SEO, and finding contributing writers. + +### What’s next + +For a thorough preparation in working with technical documentation, the +following resources are available: + +[Open Source Documentation Essentials](https://training.linuxfoundation.org/training/open-source-technical-documentation-essentials-lfc111/) +and +[Creating Effective Documentation for Developers](https://training.linuxfoundation.org/training/creating-effective-documentation-for-developers-lfc112/) +are free courses offered by CNCF and the Linux Foundation. + +[Google for Developers](https://developers.google.com) offers +[free technical writing courses](https://developers.google.com/tech-writing). + +[Docs for Developers](https://docsfordevelopers.com/) is a guide to writing +user-oriented documentation for software engineers. + +For advice and next steps with documentation for a CNCF sandbox project, contact +the [CNCF TechDocs team](https://github.com/cncf/techdocs/blob/main/README.md). From c5e5b36cbdd5781d6d5962de491aaa4d3ecec04d Mon Sep 17 00:00:00 2001 From: Dindihub <100135497+Dindihub@users.noreply.github.com> Date: Fri, 9 Aug 2024 03:06:01 +0300 Subject: [PATCH 5/5] Docs: TUF docs Analysis and Improvement (#261) --- analyses/0012-TUF/README.md | 22 ++ analyses/0012-TUF/analysis.md | 529 ++++++++++++++++++++++++++++ analyses/0012-TUF/implementation.md | 227 ++++++++++++ analyses/0012-TUF/issues.md | 151 ++++++++ 4 files changed, 929 insertions(+) create mode 100644 analyses/0012-TUF/README.md create mode 100644 analyses/0012-TUF/analysis.md create mode 100644 analyses/0012-TUF/implementation.md create mode 100644 analyses/0012-TUF/issues.md diff --git a/analyses/0012-TUF/README.md b/analyses/0012-TUF/README.md new file mode 100644 index 0000000..89b1d4a --- /dev/null +++ b/analyses/0012-TUF/README.md @@ -0,0 +1,22 @@ +# TUF Documentation Analysis + +This section contains analysis of The Update Framework (TUF) project +documentation. This is a [CNCF-techdocs](https://github.com/cncf/techdocs) group +process aimed at assisting cloud-native open-source projects with their +documentation efforts. + +The documents therein provide an analysis of +[TUF](https://github.com/theupdateframework/theupdateframework.io) existing +website documentation as of June 2024.There are suggested recommendations for +implementation and a list of GitHub Issues. Use the following list to view each +document: + +- [TUF Analysis](analysis.md) - Analyzes the existing TUF website documentation + and provides recommendations. + +- [TUF Implementation](implementation.md) - Provides detailed and actionable + recommendations. + +- [TUF Issues](issues.md) - A list of documentation improvements derived from + TUF Implementation, to be entered as issues in the + [theupdateframework.io repo](https://github.com/theupdateframework/theupdateframework.io). diff --git a/analyses/0012-TUF/analysis.md b/analyses/0012-TUF/analysis.md new file mode 100644 index 0000000..e2b1bea --- /dev/null +++ b/analyses/0012-TUF/analysis.md @@ -0,0 +1,529 @@ +--- +title: TUF Documentation Analysis +tags: TUF +created: 2024-06-17 +modified: YYYY-MM-DD +author: Sandra Dindi (@Dindihub) +--- + + + +## Introduction + +This document analyzes the effectiveness and completeness of +[The Update Framework](https://theupdateframework.io) (TUF) open source software +(OSS) project's documentation and website. It is funded by the CNCF Foundation +as part of its overall effort to incubate, grow, and graduate open source cloud +native software projects. + +TUF is a graduated CNCF project. The documentation analysis is the first step of +a CNCF process aimed at assisting projects with their documentation efforts. + +### Purpose + +This document analyzes the current state of **The Update Framework (TUF)** +documentation. It provides project leaders with an informed understanding of +potential problems in current project documentation. A second +[implementation](./implementation.md) document, outlines an actionable plan for +improvement. A third [issues](./issues.md) document, outlines the issues to be +added to the project documentation repository. These issues can be taken up by +contributors to improve the documentation. + +This document: + +- Analyzes the current TUF technical documentation and website +- Compares existing documentation against the CNCF’s standards +- Recommends a program of key improvements with the largest return on investment + +### Scope of analysis + +The documentation includes the entire contents of the website, the technical +documentation, and documentation for contributors and users on the TUF GitHub +repository. + +The TUF website and documentation are written in Markdown and compiled using the +Hugo static site generator and served on the Netlify platform. The site's code +is stored on the TUF GitHub repo. + +#### In scope + +- Website and docs: +- Website repo: +- The TUF community repository: + +- TUF specification repository: + +- TUF artwork repository: +- Python reference implementation repository: + + +#### Out of scope + +- TUF Augmentation proposals repository: + +- python-tuf: +- go-tuf: +- tuf-on-ci: + +- RSTUF: + +### How this document is organized + +This document is divided into three sections that represent three major areas of +concern: + +- **Project documentation:** Analyzes documentation for users of the TUF project + software. +- **Contributor documentation:** Analyzes documentation for existing and new + contributors to TUF project. +- **Website:** Analyzes the mechanics of publishing the documentation, including + branding, website structure, and maintainability. + +Each section begins with summary ratings based on a rubric with appropriate +criteria for the section, then proceeds to: + +- **Comments**: Observations about the existing documentation, with a focus on + how it does or does not help TUF project users achieve their goals. +- **Recommendations**: Suggested changes that would improve the effectiveness of + the documentation. + +The accompanying [implementation](./implementation.md) document breaks the +recommendations down into concrete actions that can be implemented by project +contributors. Its focus is on drilling down to specific, achievable work that +can be completed in constrained blocks of time. + +Ultimately, the implementation items are decomposed into a series of +[issues](./issues.md) that can be implemented by the project maintainers. + +### How to use this document + +Readers interested only in actionable improvements should skip this document and +read the **[implementation](./implementation.md) plan** and +**[issues](./issues.md) list**. + +Readers interested in the current state of the documentation and the reasoning +behind the recommendations should read the section of this document pertaining +to their area of concern: + +- [Project documentation](#project-documentation) + +- [Contributor documentation](#contributor-documentation) + +- [Website and infastructure](#website-and-infrastructure) + +#### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards, +and suggests possible improvements. In most cases there is more than one way to +do things. Few recommendations here are meant to be prescriptive. Rather, the +recommended implementations represent the reviewers' experience with how to +apply documentation best practices. In other words, borrowing terminology from +the lexicon of [RFCs][rfc-spec], the changes described here should be understood +as "recommended" or "should" at the strongest, and "optional" or "may" in many +cases. Any "must" or "required" actions are clearly denoted as such, and pertain +to legal requirements such as copyright and licensing issues. + +## Project documentation + +| Criteria | Rating (1-5) | +| -------------------------- | ------------ | +| Information architecture | 2 | +| New user content | 1 | +| Content maintainability | 3 | +| Content creation processes | 1 | +| Inclusive language | 3 | + +Scale: + +1 = Not present + +2 = Needs improvement + +3 = Meets standards + +4 = Meets or exceeds standards + +5 = Exemplary + +### Summary of issues + +- Information is repeated on several pages of the website. For example, the TUF + Specification file is referenced on more than one page. Some pages can be + consolidated into others. + +- The website content needs restructuring to align sections with sub-sections + related to their use case. For example, information in the sections should + correspond with the label of the section i.e _About_ should only contain + introductory content about the project. + +- The information available for news users and contributors is not satisfactory. + There are no step-to-step guides and tutorials for new users to get started + with the software, neither are there contributor guidelines. + +#### Information architecture + +- There is an _overview_ section explaining what TUF is and its use cases. The + features, the metadata and roles are well explained with examples for each + metadata. + +- Repetition of content on different pages makes content confusing + +- Re-organise content to make it easier to follow + +- There are no tutorials for specific feature implementation. But, there are + videos explaining various use cases. + +- There aren't specific task-based guides for features. +- There aren't specific task-based guides for features. + +- There is a FAQ and reporting issues sections for troubleshooting. + +- There is a well detailed API reference for multiple TUF APIs + +- README on + [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) + repo is empty with little information about the content of the repo. + +#### New user content + +- There is a _Getting started_ section on the website with information about + main features. But there's repetition of content from other pages. For example + the _Specification (latest)_ and _index_ include information present in the + project and overview sections. This section is confusing for new users. + +- The website repo does not have guides for new users or contributors to get + started + +- There isn't any documentation labeled 'Installation guide'. Instead, + installation instructions are part of a larger document labelled + [The Update Framework specification](https://theupdateframework.github.io/specification/latest) + +- TUF docs do not provide information about application-specific/OS + functionality in system updates. Instead the documentation states that TUF + provides a secure way for applications to obtain and verify files being + distributed by trusted parties. + +- There is sample code in the content that can be easily copy-pasted on other + platforms. + +- It's not clear whether the documentation is up-to-date as there are no dates + on docs or release notes published.The only document on the site with dates is + the + [Specification file](https://theupdateframework.github.io/specification/latest) + +#### Content maintainability & site mechanics + +- The documentation is not searchable. You have to go through the site to find + what you are looking for. The only source of naviagation is the menu bar. + +- The Docs are managed through docs-as-code site Hugo and content written in + markdown. However,it appears the updates are made manually. + +#### Content creation processes + +- Documentation lacks contribution process guides and information on how to get + started. + +- Documentation lacks procedures for duplicating the documentation locally. + +- It's not clear whether the code release process is synced with the + documentation creation and updates. + +- It's not clear who reviews and approves documentation pull requests and + updates either on the website or repo. + +- Information about TUF project maintainers is available on the website but not + on the project documentation repo. + +#### Inclusive language + +- I noted one instance of use of non-recommended words as documented by the + [Inclusive Naming Initiative](https://inclusivenaming.org) website. The word + _Aborted_ is used in the + [Specification index tutorial](https://theupdateframework.github.io/specification/latest/#fix-time) + +- There is no use of abliest language like simple, or easy in the documentation. + +### Project recommendations + +#### Information architecture + +- Information can be re-organized on the website to make it easier for new users + to navigate. That is, each section can contain only related information. For + example, introduce a documentation section to consolidate other pages on the + site. Much of the information in the _About_ and _Getting started_ sections + can go under a _Docs_ section + +- Provide step-by-step tutorials for users on a separate page and label it as + such. + +- Create a **README** on the website repo with information detailing the content + of the repo. Also include a **contribution guide** and information of how to + set up the website and run it locally for new contributors. You can include a + getting started section on the README. + +#### New user content + +- Include only new user content in the **Getting started** Include information + about features, tutorials and guides. Remove information about the + Specification as it's repeated in the _Project section_. + +- Include a **README** in the documentation repo with a contributor guide on how + to get started with Docs. + +#### Content maintainability & site mechanics + +- Include a search button on the website to make it easier for users to search + and find content. + +- The website repo can be the entry point of all repos. Meaning, the Docs README + can contain all the TUF project information including links to the other repos + and contributor guidelines. + +#### Content creation processes + +- Provide information about the website such as the tools used and how to set up + ad run it locally on the website repo. + +- Provide information about the contribution process including having + contribution guides on the website and the documentation repo. You can also + include contribution guidelines to avoid violations. + +- Include dates on the documentation on the website and the repo to inform users + of their relevance. + +- Include information about verified maintainers on the documentation repo. It + makes it easier for contributors to know who to contact for assistance. + +#### Inclusive language + +- Replace the word _Aborted_ mentioned in the + [Specification document](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) + with recommended suggestions in the + [Inclusive language documentation](https://inclusivenaming.org/word-lists/tier-1/abort) + +## Contributor documentation + +| Criteria | [Rating (1-5)] | +| ----------------------------------------- | -------------- | +| Communication methods documented | 3 | +| Beginner friendly issue backlog | 1 | +| “New contributor” getting started content | 1 | +| Project governance documentation | 3 | + +Scale: + +1 = Not present + +2 = Needs improvement + +3 = Meets standards + +4 = Meets or exceeds standards + +5 = Exemplary + +### Summary of Issues + +- The documentation does not contain information tailored to contributors. +- Information about TUF communication channels is not visible in the website + repo. But the information is available on the website. +- The documentation does not contain information about other project repos and + their links. Making it harder for contributors to find them. +- The documentation repo issues do not appear to be maintained. There are old + issues that are still open which may confuse contributors looking for issues + to work on. +- Information about the TUF **slack channel** is available on the website in +- Information about the TUF **slack channel** is available on the website in + areas of interest + +#### Communication methods documented + +- Information about the TUF **slack channel** is available on the website in + both the Community and Contact sections. However,this information should be + visible on the website repo README for easy access. visible on the website + repo README for easy access. + + no information about project meetings. Instead, the users are directed to join + the + [Python reference implementation](https://github.com/theupdateframework/python-tuf?tab=readme-ov-file) + +- Information about the mailing list is included in the documentation. There's + no information about project meetings. Instead, the users are directed to join + the #TUF channel on CNCF slack. + +#### Beginner friendly issue backlog + +- Issues on the docs repo are missing labels, making it hard for contributors to + identify 'Docs' issues. +- New contributors will have a hard time getting started as none of the issues + are marked "good first issue” label +- Most issues on the docs repo have a title and a detailed description. +- Issues are not maintained for staleness. There are issues opened in 2021 that + are still open with the information on their status. + +#### New contributor getting started content + +- There's a community section on the website with information on how to join the + community. +- No specific documentation tailored to new users to get started to set up the + website. +- The docs provide several channels for reporting issues, contacting the + maintainers, and slack community. + +#### Project governance documentation + +- The project governance is well documented on the website. There's sufficient + information about it's history including leaders, maintainers and + contributors. However, this information is not visible in the docs repo + README. + +### Contributor recommendations + +#### Communication methods documented + +- The website repo link may be included on the site as an entry point for the + project or the umbrella repo + [theupdateframework](https://github.com/theupdateframework) that lists all TUF + repositories. +- Include communication channels on the Docs repo README for visibility. +- Provide information about project meetings, e.g., a meeting link and calendar. + project or the umbrella repo + [theupdateframework](https://github.com/theupdateframework) that lists all TUF + repositories. +- Maintain issues, track, close, and stale old issues to reduce backlog. +- Provide information about project meetings e.g a meeting link and calendar. +- Include communication channels on the Docs repo README for visibility. +- Provide information about project meetings, e.g., a meeting link and calendar. +- Provide information about project meetings, e.g., a meeting link and calendar. + +#### Beginner friendly issue backlog + +- Maintain issues, track,close and stale old issues to reduce backlog. +- Include instructions on how to contribute to a CONTRIBUTING guideline, e.g., + how interest. + +#### New contributor getting started content + +- Include instructions on how to contribute on a CONTRIBUTING guideline e.g how + to identify issues, forking, cloning, and submitting PRs. + +#### Project governance documentation + +- Information on project governance is well documented on the website. However, + the same needs to be included in the docs repo on GitHub. + +## Website and infrastructure + +| Criteria | [Rating (1-5)] | +| ------------------------------------------- | -------------- | +| Single-source for all files | 4 | +| Meets min website req. (for maturity level) | 3 | +| Usability, accessibility, and design | 3 | +| Branding and design | 4 | +| Case studies/social proof | 5 | +| SEO, Analytics, and site-local search | 2 | +| Maintenance planning | 2 | +| A11y plan & implementation | 3 | +| Mobile-first plan & impl. | 5 | +| HTTPS access & HTTP redirect | 5 | +| Google Analytics 4 for production only | 1 | +| Indexing allowed for production server only | 1 | +| Intra-site / local search | 1 | +| Account custodians are documented | 3 | + +Scale: + +1 = Not present + +2 = Needs improvement + +3 = Meets standards + +4 = Meets or exceeds standards + +- There's no guideline or tutorial to assist users in generating the website + from 5 = Exemplary + +### Summary of Issues + +navigation option is a menu bar. This makes it difficult to find information. +the website repo. + +- Information about the website build, tools and how to generate it are not + available on the website or the docs repo. +- Intra-site search mechanism is not available from the website. The only + naviagation option is a menu bar. This makes it difficult to find information. +- Alot of empty space between the Hero section and the Navbar. Due to this + spacing, information is pushed out of eyelevel. You have to scroll down to + find it. + +#### Single-source requirement + +- All source files are in the website repo named + [theupdateframework.io](https://github.com/theupdateframework/theupdateframework.io) + +#### Minimal website requirements + +The website docs analysis is in progress. + +#### Usability, accessibility and devices + +- The website follows a mobile-first design with all pages, menu's and features + visible on smaller screens. +- There's a recognizable brand for the project, a logo, and a blue-white color +- The website does not provide a text-to-speech option for users. + +#### Branding and design + +- There's a recognizable brand for the project , a logo and blue-white color + scheme used througout the website. +- The website design is good and suitable for reading. However, consider + reducing the space between the hero section and the Navbar. + +#### Case studies/social proof + +- There are case studies documented on the website under the _Adoptions_ page. +- There's a logo, wall of users and participating organizations documented in + the _Adoptions_ page. +- No available community talks on the website. They have however provided links + to the community channel. +- The available [TUF blog](https://theupdateframework.github.io/python-tuf) page + is not available on the website. It's hosted on GitHub + +#### SEO, Analytics and site-local search + +- It's not clear what analytics are used on the site +- Intra-site search is not available from the website +- There's no mention of custodians of analytics and search. + +#### Maintenance planning + +- The website runs on Hugo and supported by the community. +- It's not clear who are the maintainers of the website. + +#### Other + +- The website is accessible via HTTPS + +### Website recommendations + +#### Branding and design + +- Reduce the empty space between the hero section and Navbar to bring + information to eyelevel. At the moment the information is too far down, you + have to scroll to find it. + +#### SEO, Analytics and site-local search + +- Provide intra-site search options such as a search button to make it easier + for users to search and find information. + +#### Maintenance planning + +- Identify website maintainers on the site and their roles so users know who to + contact in case issues arise. +- Provide information about the website build and how to generate it on the docs + repo. + +[rfc-spec]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/0012-TUF/implementation.md b/analyses/0012-TUF/implementation.md new file mode 100644 index 0000000..c5fa71d --- /dev/null +++ b/analyses/0012-TUF/implementation.md @@ -0,0 +1,227 @@ +--- +title: Implementing TUF Doc Improvements +tags: TUF +--- + +## Introduction + +This document provides actionable suggestions for improving the +**theUpdateframework (TUF)** technical documentation. + +For an analysis and general discussion of recommendations on TUF technical +documentation, see [analysis](./analysis.md). + +### Recommendations, requirements, and best practices + +This analysis measures documentation against CNCF project maturity standards and +suggests possible improvements. In most cases, there is more than one way to do +things. Few recommendations here are meant to be prescriptive. Rather, +recommendations are based on documentation best practices as understood by the +reviewers. The recommended implementations represent the reviewers' experience +with how to apply those best practices. In other words, borrowing terminology +from the lexicon of [RFCs][rfc-keywords], the changes described here should be +understood as "recommended" or "should" at the strongest, and "optional" or +"may" in many cases. Any "must" or "required" actions are denoted as such and +pertain to legal requirements such as copyright and licensing issues. + +The top-level documentation recommendations for this project are: + +- **Reorganize documentation** + + - Introduce a docs section and place some sections like **Getting started** + under it to avoid repetition + - Structure 'Getting started' according to user roles + - Add instructional material to the website and repo documentation to make it + easier to find. + +- **Introduce instructional documentation** + + - Identify TUF user roles (personas) + - Develop task-based material i.e How-tos for user roles + - Develop quick start and contribution guides for new users + +- **Content maintainability and creation process** + - Add search functionality to the website to make it easier to find content + - Identify maintainers for the website repo + - Add labels to the website repo + - Add a README to the website repo with information about the project + including links to important project repos + - Develop a contributors' guideline for new users + - Create procedural material for developing the website locally + - Include communication channels on the website repo README + - Provide information about project meetings e.g a meeting link and calendar + on both the website and repo + +## Implementation + +## Reorganize documentation + +### Align information in related sections + +Some sections listed on the menu bar have unrelated sub-sections. This structure +makes information hard to find and can be confusing to new users. Much of the +information on the website can go under a _Docs_ section. Consider the following +structure: + +- **Home page** +- **Documentation**: Overview of TUF + + - Overview: Metadata,Project,Security + - Getting started: Adopters, contributors, + - History + - Timeline + - Adoptions + - FAQ + +- **Community**: You can have two sections. + + - Learn and connect: Includes all community communication channels including + social media, mailing lists, calendars, Slack, etc. + - Develop and Contribute: Information about how to contribute to TUF + components and documentation. + - Code of conduct + +- **Resources**: + - News + - Videos + - Publications and press + +### Consolidate some pages + +The specification index is referenced several times on the website despite +having a sub-section. + +You can have a **docs section** with information tailored to the user roles of +the three project components. + +### Add user roles to the Getting Started section + +Structure the _Getting Started_ section according to user roles under a _Docs_ +section. The perceived user roles for this project are Adopters and +Contributors: + +- **Adopters**: Integrate TUF security properties into new and existing content + delivery systems. Adopters can be classified into two categories: + + - _Client maintainers_: depend on repository maintainers, to provide a TUF + repo. And they can choose from multiple TUF client implementations + (python-tuf, go-tuf, etc.) Typically, they will pick the language their + client is written in. + - _Repository maintainers_: Use either an existing TUF repository + implementation (tuf-on-ci, RSTUF), or roll their own (typically using a tuf + repository library such as python-tuf, go-tuf, etc.) + +- **Contributors**: want to contribute either to the spec or documentation. + - Spec contributors + - Docs contributors + +## Add introductory Video to homepage + +- Add a 1 minute video covering an overview of the TUF project why the project + matters. + +## Add a 'Schedule and appointment' icon to the website + +- Create 'Schedule an appointment' link on the website. This creates an avenue + for users to talk to community members to learn the project or seek + clarification. + - Spec contributors + - Docs contributors + +## Introduce Instructional Material + +- Identify user roles in the documentation and what can be achieved by each +- Create instructional material in the _Getting Started_ section for each user + role i.e how-to guides and tutorials +- Include links to the GitHub repos associated with the role. + +## Content maintainability and creation process + +### Add README to website repo + +Add a README to the website repo with information about the project. I suggest +the following information: Overview of the project, components, project repos, +communication channels and links a contributors' guide. + +### Add search functionality to website + +Consider adding a search functionality to the website to make it easier for +users to do intra-site searching. Hugo does not have such functionality so I +suggest using a plugin or migrating to a theme that has search functionality. + +### Identify maintainers for website repo + +Identify maintainers for the website repo both on the website and repo to make +it easier for contributors to contact them. + +### Add labels to the website repo + +Include labels to issues in the website repo. These include labels such as +_#docs \#Goodfirstissue_ to make it easier for contributors to get started. + +### Develop a guidelines for new users and contributors + +Develop contributor guides to assist new contributors to get started. + +### Create procedures for developing the website locally + +Develop procedures for developing the website site locally i.e. cloning, +building, and serving the documentation. You can also provide information about +the tools used to build and maintain the site. When such information is +available it helps contributors know how to improve the website. You might get +some good suggestions. + +### Provide project meeting links and calendar + +Provide information about project meetings and a calendar on both the website +and repo. Makes it easier for contributors to sync with their calendars and get +notifications about meetings. I like how the +[**Meshery**](https://github.com/layer5io/layer5) project has implemented this. + +## Proposed Information Architecture for the TUF Website + +The table below outlines the current information architecture(IA) of the +[TUF website](https://theupdateframework.io/) and the proposed IA for the new +website. + +| Website | Section | Subsections | +| ------------------------ | --------------- | ------------------------ | +| **Current TUF Website** | Homepage | | +| | About | - Overview | +| | | - History | +| | | - Timeline | +| | | - Project | +| | | - Publications | +| | | - Code of conduct | +| | Getting Started | - Roles and metadata | +| | | - FAQ | +| | | - Specification (latest) | +| | | - Specification index | +| | | - Implementations | +| | | - Videos | +| | Community | - Adoptions | +| | | - Reporting issues | +| | | - Security audits | +| | | - Proposals | +| | | - Contribute | +| | | - Chat (CNCF Slack) | +| | News | | +| | Contact | | +| **Proposed TUF Website** | Homepage | | +| | Docs | - Overview | +| | | - Project | +| | | - Enhancement proposals | +| | | - Metadata | +| | | - Security audits | +| | | - Getting started | +| | | - Adoptions | +| | | - FAQ | +| | Community | - Code of conduct | +| | | - Learn and connect | +| | | - Develop and contribute | +| | Resources | - News | +| | | - Publications and press | +| | | - Videos | +| | | | + +[rfc-keywords]: https://www.rfc-editor.org/rfc/rfc2119 diff --git a/analyses/0012-TUF/issues.md b/analyses/0012-TUF/issues.md new file mode 100644 index 0000000..9ffb2b8 --- /dev/null +++ b/analyses/0012-TUF/issues.md @@ -0,0 +1,151 @@ +--- +title: TUF Issue +tags: TUF +--- + +## Overview + +This issue tracks recommended changes resulting from an analysis of the TUF +documentation commissioned by CNCF. The analysis and supporting documents are +here: under +`0012-TUF`.This is a master list of issues recommended in the TUF tech doc +analysis and implementation plan. + +## Issues + +### Reorganize website content + +Reorganize website content by introducing new sections and consolidating some +pages. For example, a docs section can accomodate most pages on the website. +View the proposed outline in the [Implementation document](./implementation.md) + +This proposed change consolidates related pages and removes others, chnaging the +structure of the current website +[theupdateframework.io](https://theupdateframework.io/) + +Audience: Admin + +Type: Conceptual + +### Categorize new user information according to user roles + +Structure the _Getting Started_ section according to user roles. The identified +user roles are _Adopters_ and _Contributors_. + +These can be further broken down into subsections depending on use case: + +- Adopters : + - Client maintainers + - Respository maintainers +- Contributors: + - Spec contributors + - Docs contributors + +View the [Implementation document](./implementation.md) to understand the user +roles and the kind of information targeting each role. + +You can add an _Edit this page_ button on website and link it to the doc +repository for doc contributors. + +Audience: Admin + +Type: Conseptual + +### Add introductory Video to homepage + +- Add a 1 minute video covering an overview of the TUF project why the project + matters. + +Audience: Admin + +Type: Conseptual + +### Add a 'Schedule and appointment' icon to the website + +- Create a _Schedule an appointment_ link on the website footer section. It can + also appear on the community page. + +Audience: Admin + +Type: Conseptual + +### Introduce Instructional material for user roles + +Create instructional material in the _Getting Started_ section for each user +role i.e configuration guides and tutorials. Include links to the GitHub repos +associated with each role. + +Audience: Developer + +Type: Task + +### Add README to website repo + +Add a README to the website repo with information about the project. You can +provide an overview of the project, links to other project repos, communication +channels, contributors' guide and a link to the deployed website on the _About_ +section on GitHub. + +This provides comprehensive information for anyone coming across the repo on +GitHub. + +Audience: Contributor/Admin + +Type: Conceptual + +### Add search functionality to website + +Though not priority, a search functionality helps users easily navigate the +website. The proposed Docsy theme has a search functionality that easy to adopt. + +Audience: Developer + +Type: Task + +### Identify maintainers for website repo + +Identify maintainers on the website repo both on the website and repo to make it +easier for contributors to contact them. This information can be added to the +Readme + +Audience: Admin + +Type: Conceptual + +### Add labels to the website repo + +Add labels to issues in the website repo to make it easier for contributors to +identify suitable issues. Labels such as _#docs \#Goodfirstissue_ make it easier +for contributors to get started. + +Audience: Admin + +Type: Task + +### Develop a guidelines contributors on website repo + +Develop contributor guides to assist new contributors to get started. + +Audience: Admin + +Type: Task + +### Create procedures for developing the website locally + +Provide procedures for developing the docs site locally i.e. cloning, building, +and serving the website. You can also provide information about the tools used +to build and maintain the site e.g :Hugo site, Docsy theme, served on Netlify. + +Audience: Contributor + +Type: Task + +### Provide project meeting details and calendar on website repo + +Information on the communication channels on the +[Community repo](https://github.com/theupdateframework/community) can be also +added to the deployed website and the website repo. + +Audience: Contributor + +Type: Task