etcd-io / etcd-io/website

Make the Developer Guide task-oriented

Open
#769 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

Rewrite instructional sections in this guide to be step-by-step tasks. Move reference material into an omnibus reference section or into a reference section at the end of the Developer Guide. (See separate issue concerning reference section.)

Audience: Developer

Type: Task

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

Related material in the current doc:

https://etcd.io/docs/v3.5/dev-guide/

Since there are such a large number of APIs and supported interfaces, consider organizing this information by language or providing an index page to language-specific task and reference pages.

Following are comments on some of the existing sections within the Developer Guide.

- [ ] *Discovery service protocol*: What is the use case for this information? If it's to enable a developer to programmatically discover a cluster, leave it here. It might also belong in the Operations guide, perhaps in the Clustering Guide (but link to the same page, don't duplicate it).

- [ ] *Set up a local cluster*: Make this the first section in the Developer guide. Link from the Developer Quick start -- this is the server install that a developer should see first, not the (Production) Install page.

- [ ] *Why gRPC gateway*: This section is mostly about how to use the gRPC gateway. Put the introductory material (that describes why you'd want to use gRPC) in the system overview. Present the rest as a task or tasks in the Tasks section of the Developer Guide. A complete reference to the options should be available in the Reference section.

- [ ] * gRPC naming and discovery*: Include the tasks from this section in the gRPC section of the Developer tasks. Include explanatory material in the system overview with the gRPC explanation.

- [ ] *etcd features*: This information is a duplicate of the [Features](https://github.com/etcd-io/etcd/blob/main/Documentation/contributor-guide/features.md) maturity information in the repo. Remove from the Developer guide, but reference the repo Features article from the release notes.

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.