etcd-io
Update quickstart and new user workflows
Overview
~Rename to "Quick start" (two words)~. Add a "Prerequisites" section and revise the "What's next" section to focus on two separate paths, Development and Operations. Write separate "Getting started" workflows for Developer and Operator users. For the developer path, link to the "Set up a local cluster" page rather than the install page.
Audience: All
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://github.com/etcd-io/website/blob/main/content/en/docs/v3.5/quickstart.md
Usage varies, but the Etc docs have used Quickstart (one word) from the start (or at least for a while now), as do other sites like GH, see:
If we break down the opening comment guidance, I see these tasks:
- (1) ~Rename to "Quick start" (two words).~ See https://github.com/etcd-io/website/issues/782#issuecomment-2688630047.
- (2) Add a "Prerequisites" section
- (3) Revise the "What's next" section to focus on two separate paths, Development and Operations
And:
- (4) Write separate "Getting started" workflows for Developer and Operator users.
- For the developer path, link to the "Set up a local cluster" page rather than the install page.
I'm assuming that the separate "Getting started" workflows refer to separate pages, not to be crammed into the single Quickstart page, right @dwelsch-esi?
/cc @nate-double-u
Ah, I'm recalling why there wasn't a separate "Prerequisites" section. If you look at the current Quickstart, it is sooo simple, that it didn't make sense at the time to separate out the Prerequisites from the steps.
Also, @dwelsch-esi, have you outlined somewhere how you see the separate "Getting started" workflows taking shape?
(4) Write separate "Getting started" workflows for Developer and Operator users.
- For the developer path, link to the "Set up a local cluster" page rather than the install page.
I'm assuming that the separate "Getting started" workflows refer to separate pages, not to be crammed into the single Quickstart page, right @dwelsch-esi?
Just my two cents, if they were to be separate pages, then the "Quickstart" should still refer to those pages, no? Maybe have the "What's next" section refer to the "Getting started" pages, one located at the beginning of each flow?
So one for dev-guide and one for op-guide
@dwelsch-esi I would like to ask a few clarifications:
- To my understanding, the current bullet points in the What's next can be removed to be replaced with only the 2 paths mentionned (Developer and Operator users). Correct?
- Are there any acceptance criteria or templates for the Prequisites sections?
/assign
@ronaldngounou :
@dwelsch-esi I would like to ask a few clarifications:
1. To my understanding, the current bullet points in the What's next can be removed to be replaced with only the 2 paths mentionned (Developer and Operator users). Correct? 2. Are there any acceptance criteria or templates for the Prequisites sections?/assign
- Yes, though if there really are more things that the user might want to do from this point, one solution would be to create sub-lists:
- If you're a developer:
- Explore the gRPC API
- Find language bindings and tools
- If you're an operator or admin:
- Set up a multi-machine cluster
- Learn how to configure etcd
- Use TLS to secure an etcd cluster
- Tune etcd
I'm a little dubious that all of these would be equally relevant to a new user, though. The goal is to guide the user to what is probably the next important step in their learning process. For the operator especially, I don't think they'll be interested in TLS, for example, until they've set up a cluster. At that point I'm sure they can find TLS in the User/Admin Guide.
-
I don't have any templates for Prereq sections. That's a good idea, though. If you write one, I'd format it as a checklist of items to consider including. It's not entirely cut and dried; sometimes an item can go in the prereqs or in the procedure. Here are some guidelines for what to consider including:
- Hardware requirements, if any, including minimum specs for performance, and any peripherals required
- Platform: OS, including version; installed languages; and software dependencies, including versions
- Security requirements, including certificates or keys, if they're not part of the task
- Environment, including paths and configurations that should already be set up
- Processes that must be running, including daemons, clusters, agents, and servers
- Installed software required to perform the steps of the task, including CLIs, APIs, and IDEs
Again, some of these things might be part of the task; in a lot of cases that's a judgement call. For example, I'd include a path variable in the prereqs if it were required for a dependency (so it should be there already), but if it directly supported the task in question I'd include it as a step in the procedure.
If you want to take things to the next level, another way to think about this is to imagine things that could go wrong with your procedure and try to head them off with prerequisites. A lot of times as a developer you might miss prerequisites because they're already so ingrained in your routine or buried in your environment. Look for where you say things like "Of course that will already be installed ..." or "No one would set this up without ..." or the classic "It works in my environment."
dwelsch-esi For the second task, to my understanding, that should summarize the commands to be able to launch "etcd or etcdctl in a virtual environment.
That would include all the set up steps between between 1. and 2. on this Quickstart ? I am thinking about doing similar to 01-prerequisities and 02-jumpbox but I am not sure if it is what you are looking for.
I would appreciate if you could provide additional examples on the Prerequisites step.
- These changes should be done in v3.5 or v3.6 ?