etcd-io / etcd-io/website

Reorganize the documentation

Open
#784 1 comment 0 reactions 0 assignees View on GitHub
enhancement help wanted
Dominant language
HTML
Stars
194
Forks
354
Avg merge
9d 12h
Merged PRs (30d)
3

Description

## Overview

Move reference and conceptual topics out of the task-based documentation and into their own (new, if necessary) sections. Write documentation as needed to fill gaps in the conceptual or reference sections.

Audience: All

Type: All

The existing documentation might contain helpful source material that you can pull into this doc change. See recommendations for the existing (at the time of the CNCF tech doc analysis) etcd technical documentation pages:
https://github.com/cncf/techdocs/blob/main/assessments/0010-etcd/etcd-implementation.md/#general-reorganization

## 🎤 Context

This issue tracks recommended changes resulting from an analysis of the etcd documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/assessments/0010-etcd/

## ✌️ Possible Implementation

Reorganize the documentation to follow this suggested outline:

- Architectural and system overview (Much of the current "Learning" section)
- "Start here" overview:
- Explanation of user roles and use cases
- Quick start for each user role
- Detailed installation and configuration for each user role (Contents of current "Installation" page plus Local cluster install)
- Developer guide
- Operator guide
- Standalone etcd
- Kubernetes backstore
- Troubleshooting
- Reference
- Configuration
- CLIs
- APIs
- Logs and error messages
- Glossary
- Release notes

The goal is to organize the site around the task documentation so that users can find instructions for what they need to do quickly and navigate there directly. Conceptual and reference information should be separate, and linked where necessary to support this goal.

The following tables contain suggested ToC additions, page deletions, and page moves. Conceptual and task documentation requiring writing or rewriting are described in separate Issues.

### Add sections

Sections to be added to the table of contents.

| Section | Description |
| -- | -- |
| Reference | A library of reference documents: APIs, CLIs, configuration options, and anything else a user might need to look up to complete a task. |
| Troubleshooting | A list of procedures for diagnosing and fixing problems. |
| Release Notes | The cumulative release notes for the major and minor release. See [Release Notes](#add-release-notes-to-new-releases).

### Remove pages

Pages to be removed entirely or cannibalized and their contents integrated elsewhere. Links (listed in the table) will need to be removed or updated as well. If the page duplicates or largely overlaps information on another page, that page is listed as "Redundant with". Page URLs are relative to `https://etcd.io/docs/v3.5/`.

| Page | Links | Redundant with | Suggested action |
| -- | -- | -- | -- |
| demo/ | | op-guide/authentication/authentication/ | Remove |
| dev-internal/discovery_protocol/ | op-guide/clustering/ | dev-guide/discovery_protocol/ | Remove |
| /dev-guide/interacting_v3/ | dev-guide/local_cluster/ | tutorials/*.md | Consolidate under "Tasks". See [Tutorials](#tutorials) |
| op-guide/recovery/ | op-guide/failures/, op-guide/runtime-configuration/, op-guide/runtime-reconf-design/ | | Incorporate into Troubleshooting guide |
| op-guide/data_corruption/ | op-guide/monitoring/ | | Incorporate into Troubleshooting guide |
| upgrades/ | | | Remove or archive old upgrade paths if they're no longer needed or supported. |
| dev-guide/features/ | | | Remove from the Developer guide. See [etcd features](#etcd-features). |

### Move pages

Pages to be moved as-is, usually under an organizing heading. Links (listed in the table) will need to be updated. Page URLs are relative to `https://etcd.io/docs/v3.5/`.

| Page | Links | Suggested action |
| -- | -- | -- |
| metrics/ | | Move to the Operations Guide. |
| learning/glossary/ | | Move to Reference section. |
| tuning/ | op-guide/hardware/, quickstart/ | Move to the Operations Guide. |
| dev-internal/logging/ | | Move to the Reference section. Link from the Operations guide. |
| dev-internal/modules/ | | Move to Architecture overview. |
| integrations/ | quickstart/ | Move to the Reference section. Consider organizing by user role , or labeling each tool or library by user role. |
| integrations/#projects-using-etcd | quickstart/ | Move to a logo wall or at least to its own page on the website. |
| reporting_bugs/ | | Combine with the "Triage" topics and move to the repo's Contributor guide. Link from the Troubleshooting guide. |
| faq/ | | Move to near the end of the ToC. |
| dev-guide/api_reference_v3/ | op-guide/runtime-configuration/ | Move to the Reference section. |
| dev-guide/api_concurrency_reference_v3/ | | Move to the Reference section. |
| op-guide/container/ | | Put in the Clustering Guide. |
| op-guide/configuration/ | quickstart/ | Put in the Reference section. |
| upgrades/ | | Move to the Operations guide. |
| triage/ | | Move to the repo and provide a link from the documentation (release notes) to create a cleaner separation of product documentation and project documentation. |

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.