etcd-io / etcd-io/website

Consolidate all reference information

Open
#768 0 comments 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

Consolidate all reference information to a reference-specific section.

Or, create user role-specific reference sections within the Developer and Operations guides. Since some of the material overlaps, a single reference section is probably easier.

Reference documentation includes API, CLI, and configuration references, the glossary -- any topic that presents a comprehensive "lookup" document.

Audience: All

Type: Reference

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

The top-level Reference section should be clearly labeled as such and visible from everywhere in the documentation; the best place is probably as a top-level entry in the table of contents (TOC) that appears in the left sidebar. The TOC link should bring up an index of all reference pages with links.

If there is documentation that's auto-generated or extracted from code (APIs, for example), it's permissible -- preferred, in fact -- to link to such documentation. This avoids the churn and errors that accompany duplicating and trying to maintain such documentation in two locations.

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.