---
name: writing-practitioner-guides
description: Use when writing hands-on guides, runbooks, troubleshooting docs, lab walkthroughs, or validation procedures that a human will execute themselves in a terminal over SSH. Symptoms that this applies - the reader is expected to type the commands, the doc teaches how to read a system rather than reporting a result, or a draft contains python -c, embedded JSON parsing, one-liners nobody types by hand, or a config file or YAML authored with printf/echo >>/heredoc instead of an editor.
---

# Writing Practitioner Guides

## Overview

**Optimize for human operation, not command compactness.**

A guide is not a script. The reader types each command, reads its raw output,
and decides what to do next. Commands that are efficient for an agent to run
once are often useless for a human learning to read a system.

The failure this prevents: an agent writes `curl … | python3 -c 'import json…'`
because it produces a clean answer in one call. The reader gets the answer and
learns nothing about the tool they will need at 3am.

## The boundary

Three tiers. Pick the lowest one that fits.

```
interactive command  →  short pipeline  →  saved script file
```

| Tier | When | Form |
|---|---|---|
| **interactive** | reading state, one question | `kubectl get pods`, `ss -lntp`, `journalctl -u nginx -n 50` |
| **short pipeline** | filtering that a person would actually type | `ps aux \| grep java`, `… \| jq .status`, `for p in a b; do … done` |
| **saved script** | it has become a program | write the file with an editor, then run it |

**Move to a saved script when any of these is true:**
- multiple branches (`if`) or nested loops
- combining several requests and computing across them
- non-trivial JSON transformation
- you cannot tell what it does by reading it once
- it will be run again later

For a saved script, the guide says to open an editor, shows the code as a
**separate file listing** (not a terminal command), then shows the run command.

```bash
vim scripts/check_sessions.py
```
```python
# file: scripts/check_sessions.py
...
```
```bash
python3 scripts/check_sessions.py
```

Terminal command ≠ program source. Never blur them with a heredoc.

## Files the reader has to understand before changing them

The tiers above stop at the saved script. The same split reaches further: **any
file whose content the reader must read and understand to change it is written
in an editor, not assembled by a shell one-liner.** Config files and YAML are
that kind of file.

> **조회·진단·실행은 CLI를 적극 사용하고, 사람이 내용을 이해하면서 작성해야 하는 설정 파일은
> 에디터를 사용한다.**

| Reading or acting on the system → CLI | Authoring a file a human must understand → editor |
|---|---|
| CPU flags → `grep /proc/cpuinfo`, `lscpu` | cloud-init YAML → `nano kc-lab-1.yaml` |
| service state → `systemctl status` | systemd unit → `sudo nano /etc/systemd/system/x.service` |
| VM state → `virsh list --all` | `nginx.conf` → `sudo nano /etc/nginx/nginx.conf` |
| network → `ip addr`, `virsh net-list --all` | `~/.bashrc` → `nano ~/.bashrc` |
| logs → `journalctl -u x` | Kubernetes manifest → `nano deploy.yaml` |
| fetch / copy → `curl`, `cp`, `scp` | a script → `nano x.sh` → `chmod +x x.sh` → `./x.sh` |
| create a VM → `virt-install` | |

### This rule is not "replace sed with nano"

> 단순히 **「`sed`를 `nano`로 바꿔라」**라고 하면 안 됩니다. 그러면 모든 shell 명령을 기계적으로
> 에디터 작업으로 바꿀 가능성이 큽니다.

The trigger is the *file-authoring step*, not the appearance of a shell tool.

| Kind | Examples | Verdict |
|---|---|---|
| what an operator types by hand | `virsh`, `systemctl`, `ssh`, `curl`, `virt-install` | keep |
| reading / diagnosing | `grep`, `lsmod`, `cat`, `stat`, `groups` | keep |
| shell tricks that author a file | `printf >`, `echo >>`, `cat <<EOF`, `python3 -c`, `ssh '… cat > …'` | rewrite as an editor step |

A pipe is not the problem. A 12-line `virt-install` is not the problem —
creating the VM *is* that command's purpose, so the CLI is the right way to show
it. `sed` is fine for a query or a throwaway substitution; it is wrong as the
default interface for editing config, because what the reader will actually do
during an incident is open the file and read what is in it.

### Rewrite: `~/.bashrc`

```bash
# before
echo 'export LIBVIRT_DEFAULT_URI=qemu:///system' >> ~/.bashrc
virsh uri
```

```bash
# after
nano ~/.bashrc
```
```text
export LIBVIRT_DEFAULT_URI=qemu:///system
```
```bash
source ~/.bashrc
virsh uri
```

Two reasons, and the second is the one that gets forgotten:

1. The reader sees the chain — file → variable → reload this shell → `virsh`
   now resolves that URI. `echo >>` produces only the end state.
2. **`echo >>` is not idempotent.** Someone who walks the guide a second time
   appends the same line again. Opening the file shows what is already there.

### Rewrite: cloud-init meta-data

```bash
# before
printf 'instance-id: kc-lab-1-%s\nlocal-hostname: kc-lab-1\n' "$(date +%s)" > meta-kc-lab-1
```

```bash
# after
nano meta-kc-lab-1
```
```yaml
instance-id: kc-lab-1-20260912
local-hostname: kc-lab-1
```
> `instance-id`는 이전 cloud-init 실행과 다른 인스턴스로 인식시키기 위해 이전 값과 겹치지 않게
> 지정한다.

The `printf` form makes the reader decode `%s`, `\n`, `$(...)`, `date +%s` and
`>` before reaching the two keys the page is about. A document teaching
cloud-init should not be teaching shell `printf`. The editor form also gives the
one line about `instance-id` a place to sit, right where it is typed.

### Rewrite: a file on a remote host

```bash
# before
ssh donghyeon@192.168.122.11 'umask 077; cat > ~/kc-lab-2.yaml' < kc-lab-2.yaml
ssh donghyeon@192.168.122.11 'cloud-init schema -c ~/kc-lab-2.yaml; rm -f ~/kc-lab-2.yaml'
```

```bash
# after
scp kc-lab-2.yaml donghyeon@192.168.122.11:~/
ssh donghyeon@192.168.122.11
```
then, on the guest:
```bash
chmod 600 ~/kc-lab-2.yaml
cloud-init schema -c ~/kc-lab-2.yaml
rm ~/kc-lab-2.yaml
```

The first line asked the reader to hold SSH, redirection, `umask`, file creation
and local stdin at once. The rewrite uses more commands and puts fewer things in
each: **one action, one command.** In a guide someone is learning from, that
trade is the right way round.

One more rewrite belongs to this rule — replacing a `python3 -c` YAML check with
the format's own validator. It sits in **Command priority** below, where the
ranking it changes lives.

## Command priority

| Rank | Reach for | Examples |
|---|---|---|
| 1 | the system's own CLI | `kubectl`, `systemctl`, `psql`, `redis-cli`, `docker compose` |
| 2 | standard OS tools | `ps`, `ss`, `lsof`, `free`, `top`, `dmesg` |
| 3 | network / protocol tools | `curl`, `dig`, `openssl`, `nc`, `tcpdump` |
| 4 | short Unix combinators | `grep`, `jq`, `awk`, `head`, `tail`, `less`, `watch` |
| — | **avoid** | python/node heredocs, `python -c` that *processes data*, giant awk programs, pipelines built to produce one tidy answer |

**The line is doing-the-work vs checking-a-fact, not the language.**

```bash
# not fine — this is data processing the native tool should do
curl -s "$URL" | python3 -c '
import json,sys
for r in json.load(sys.stdin)["data"]["result"]:
    print(r["metric"]["pod"], r["value"][1])'
```

That one iterates, reshapes, and formats. `jq`, or the tool's own
output flag, does that — and when neither is installed, say so and show the
raw output instead of writing a parser.

`grep`, `jq`, `awk`, and a one-line `for` are what practitioners type. Do not
ban them. Ban the ones written for the *agent's* convenience.

### Validate with the format's own checker first

Checking a fact is allowed — but a hand-rolled syntax check is the *last*
resort, not the default. If the domain ships a command that validates this file,
that command is the step. Drop to a one-line syntax check only when nothing
validates the format.

```bash
# before — checks that it parses as YAML, and nothing else
python3 -c 'import yaml,sys; yaml.safe_load(open("kc-lab-1.yaml")); print("YAML OK")'

# after — the domain's own validator: schema, keys, and deprecations too
cloud-init schema -c ~/kc-lab-2.yaml
```

Same rank elsewhere: `nginx -t`, `sshd -t`, `systemd-analyze verify x.service`,
`kubectl apply --dry-run=server -f deploy.yaml`, `terraform validate`,
`docker compose config`. Each one is also the command the reader will reach for
when the service refuses to start, which a `python3 -c` line never becomes.

### Two shapes of the same tool

Most tools have a *reading* form and a *value-extracting* form. Pick by what
the reader does next with the output.

| The reader will… | Form | Example |
|---|---|---|
| **look at the response** and judge | reading form | `curl -I <url>` · `curl -v <url>` |
| **compare or count the value** across runs or hosts | extracting form | `curl -s -o /dev/null -w '%{http_code}\n' <url>` |

The extracting form hides everything except the field you chose. Use it only
when that field *is* the answer — a status code you will compare before and
after an injection, or a number you will repeat 900 times. When the reader is
still figuring out what is wrong, they need the headers and the TLS handshake,
not `200`.

Same split elsewhere: `kubectl get` (read) vs `-o jsonpath=` (extract),
`systemctl status` (read) vs `systemctl show -p X --value` (extract),
`psql` interactive (read) vs `psql -tAc` (extract).

**Show the reading form first at least once per tool.** A reader who has only
ever seen `-w '%{http_code}'` cannot debug a TLS error.

## Progressive narrowing

Never jump to the precise command. Show the widening-to-narrowing path the
reader will actually walk.

```
list / status  →  detail / describe  →  logs  →  targeted inspection
```

```bash
kubectl get pods                       # what is there
kubectl get pods -o wide               # where, and on which node
kubectl describe pod api-7c874-8m2js   # why is this one unhappy
kubectl logs api-7c874-8m2js           # what did it say
kubectl logs api-7c874-8m2js --previous  # what did it say before it died
```

**Observe before filtering.** Show the raw output at least once before piping
it. A reader who has never seen `ss -lntp` output needs to see it whole.

## Mutation ordering

```
observe → diagnose → reproduce → mutate
```

`rm`, `kill`, `delete`, `UPDATE`, restart, config change do not appear in the
diagnosis phase. If a step changes state, say what it changes and how to undo it.

## Shape of one step

Four elements, in this order. A command with no interpretation is not a step.

```
무엇을 확인하는가        one line — the question this answers
$ command                the command, short
어디를 봐야 하는가        which field/line in the output matters
이 결과가 의미하는 것     what it tells you, and what to do next
```

Show the real output. If it was measured, quote it verbatim; if it is
illustrative, say so.

### When the step changes state

The four elements above are the shape of a step that **reads**. A step that
**changes state** needs a different one — otherwise the why, the failure
symptoms and the special cases all pile into the same paragraph:

> 정보 밀도는 높은데 **처음 따라 하는 사람의 시선 이동이 어렵습니다.**

```
목적 → 행동(번호 매긴 명령) → 예상 결과 → 왜 필요한가 → 문제가 생기면
```

```text
### 4. libvirt 기본 연결을 system으로 설정한다

목적
virsh가 사용자 세션이 아니라 시스템 libvirt에 연결되도록 한다.

1. 설정 파일을 연다.
$ nano ~/.bashrc

2. 다음 줄을 추가한다.
export LIBVIRT_DEFAULT_URI=qemu:///system

3. 저장한 설정을 현재 셸에 반영한다.
$ source ~/.bashrc

4. 확인한다.
$ virsh uri

예상 결과
qemu:///system

왜 필요한가
qemu:///session과 qemu:///system은 서로 다른 libvirt 연결이다.
VM을 system 쪽에 만들고 virsh가 session 쪽을 보고 있으면
VM을 만들었는데도 목록에서 찾지 못할 수 있다.

문제가 생기면
$ virsh uri
부터 확인한다.
```

**A step that only reads takes the first shape; a step that changes state takes
this one.** Same headings every time, so the reader's eye lands in the same
place on step 11 as on step 1.

## Verify before publishing

Every command in a guide must have been run, or be marked as unverified.
**Check that the tools you reach for are actually installed on the machine
the reader will be on** — `jq` and `yamllint` are absent more often than you
expect, and a guide that assumes them sends the reader to install things
mid-diagnosis.
Two failures this catches, both real:

- `kubectl get endpoints` — deprecated since v1.33, prints a warning
- `kubectl exec keycloak-0 -- curl …` — the image has no curl, exit 127

A guide that teaches a stale or failing command makes the reader doubt their
own environment.

## No placeholders

`<token>` puts the value outside the document. Give the command that produces
it. For secrets, confirm existence or length — never print the value.

```bash
TOKEN=$(ssh node1 'sudo cat /var/lib/rancher/k3s/server/node-token')
echo "${#TOKEN} chars"
```

One exception: a value an earlier step already printed on screen, which the
reader carries into a later step in a different shell — a session id, a realm
UUID. The producing command is already in the document, so the value is not
outside it. Write that slot as `{{NAME}}` (uppercase, digits, underscore), and
say in the prose above the block which step printed it.

Not `${NAME}` — guides use `$TOKEN`, `$SID` and friends as real shell
variables, and a reader who reads a placeholder as one will paste it unchanged.
`{{ }}` is not shell syntax, so pasting it fails where the reader can see it.

## Rationalization table

| Excuse | Reality |
|---|---|
| "The pipeline gives a clean answer" | The reader needs to read the raw output, not your summary of it |
| "python -c is shorter than explaining" | It is shorter for you. The reader learns nothing and cannot adapt it |
| "jq/awk are also programming" | They are what practitioners type. The line is *program vs command*, not *language* |
| "I'll show the efficient way" | Efficient for one run. This doc is for someone learning to read the system |
| "The reader can copy-paste it" | Copy-paste is not the goal. Knowing where to look is |
| "I verified the logic mentally" | Run it. Two commands in a recent guide were wrong and both looked right |
| "It's obvious what this output means" | Then write the one line. If it is obvious it costs nothing |
| "`-w '%{http_code}'` is precise" | Precise about one field. The reader debugging TLS needs `-v`, not `200` |
| "It's fewer commands" | Fewer for you to type. The reader cannot tell which action they are in the middle of |
| "The file ends up the same either way" | Only on the first run. `echo >>` appends again every time someone repeats the guide |
| "So I should use nano for everything" | No. The trigger is authoring a file the reader must understand. `grep`, `virsh`, a long `virt-install` stay as they are |
| "`python3 -c` only checks syntax" | Then it misses the schema. If the format has a validator — `cloud-init schema`, `nginx -t`, `--dry-run` — that is the step |

## Red flags — stop and rewrite

- `python3 -c` or a `<<'PY'` heredoc inside a guide
- JSON parsed with a language runtime instead of `jq` or the tool's own `-o`
- a pipeline whose purpose you cannot state in one clause
- a command with no "what to look at" line under it
- `delete`/`kill`/`restart` before any observation step
- `<placeholder>` with no command that produces it
- output shown that you never actually ran
- only the extracting form of a tool appears, never the reading form
- a config file or YAML built with `printf >`, `echo >>`, or `cat <<EOF`
- one line stacking connect + redirect + file creation (`ssh host 'cat > f' < f`)
- `python3 -c` checking syntax when the format has its own validator
- a step that appends, so walking the guide twice appends the line twice

## References

Per-technology command vocabulary — what practitioners reach for first, not
an encyclopedia. Load only the one you need.

- [kubernetes.md](references/kubernetes.md)
- [linux-systemd.md](references/linux-systemd.md)
- [networking-tls.md](references/networking-tls.md)
- [datastores.md](references/datastores.md)