Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert tutorials to tasks #765

Open
Tracked by #766 ...
dwelsch-esi opened this issue Feb 13, 2024 · 1 comment
Open
Tracked by #766 ...

Convert tutorials to tasks #765

dwelsch-esi opened this issue Feb 13, 2024 · 1 comment
Labels
enhancement New feature or request help wanted Extra attention is needed

Comments

@dwelsch-esi
Copy link
Contributor

Overview

Rename the "Tutorials" section "Tasks". Split this Task section by user role and put the resulting two sections in their respective user guides: Developer and Operations.

Rename each task by removing "How to" and using the "-ing" verb form. Make steps in each task explicit; one-step tasks are okay.

Rewrite each task as step-by-step instructions for a single task in an individual description. The goal is to walk the user through the completion of the task. For example, the [How to access etcd][access-tutorial] tutorial should be two separate tasks: "Writing to etcd on the CLI" and "Reading from etcd on the CLI".

Audience: The user role to which the task most applies, probably either Developer or Operator.

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:

Suggested changes:

Use the following outline for each task:

  • Prerequisites (bullet list of prerequisite conditions, if any)
  • Procedure
    1. Step 1 (keep steps discrete and atomic. Put command-line input and expected output in a code block.)
    2. Step 2 ...
  • Result (optional; describe output or side effects if they're notable or unexpected.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

3 participants