envoyproxy/envoy

[RFC] Move developer docs to main docs (or at least to an .rst tree)

Open

#13,431 opened on Oct 7, 2020

View on GitHub
 (17 comments) (0 reactions) (0 assignees)C++ (5,373 forks)batch import
area/docshelp wanted

Repository metrics

Stars
 (27,997 stars)
PR merge metrics
 (Avg merge 8d) (378 merged PRs in 30d)

Description

description

At the moment there are a lot of useful dev docs/info spread through files in the repo.

I believe there are several advantages to centralizing the developer docs and bringing them into the main documentation

  • we have various ci/checks etc that are only applied to the doc/rst tree
  • centralizing docs would decrease the learning time/curve for new developers to find relevant documentation/adopt related standards etc
  • one set of documents to maintain (altho i think there is an argument for maintaining the dev docs in a separate tree - but then 2)

we could still leave stubs/links in README files or similar

perhaps this pertains differently to code documentation in the actual source etc than to eg ci/tooling/sandbox docs - but even then there maybe a similar argument to collate the developer docs.

Contributor guide

Research direction
Review the existing developer documentation spread across the repository and propose a structure to integrate them into the main docs tree.
Tech stack
cpp
Domain
documentation
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Git
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75