Knowledge-Base Runbook Project and Self-Test
Project goal
Write a runbook for a fictional “local meeting-summary script.” The project assesses document quality only; it does not require you to create or run a script. A reader should be able to judge the environment, procedure, expected result, failure handling, and safety boundaries from scratch. Work independently first, then view the reference answer. Commands in the reference answer are teaching scenarios too; they do not imply a corresponding script exists in the repository.
Task scenario and deliverable
- Scenario: the script reads only local UTF-8 meeting text and a local
config.json, then writes a local Markdown summary draft. It does not access the network or send messages. - Deliverable: one note named
meeting-summary-runbook.md. Do not write the exercise file into this knowledge base’s formal course directory. - Audience: a beginner who can open PowerShell but does not understand Python projects.
- Evidence boundary: you may write “expected output,” but must not label an unrun command “verified passing.”
- Safety boundary: use only fictional meeting content and placeholder paths; do not use real recordings, client information, or credentials.
Required structure
Metadata
Frontmatter contains at least title, tags, and aliases. Put only searchable metadata in Properties and place detailed explanation in the body.
Overview and boundaries
State that the script transforms local fictional meeting text into a summary draft; it does not connect to a real meeting system, send automatically, or read real credentials.
Prerequisites
List Windows 11, PowerShell 7, and Python 3, including commands that verify them. Do not promise a particular version that has not been checked.
Procedure
Number commands in order. For each section, state purpose, current directory, command, expected output, and a stop condition on failure. Use different language fences for commands and output.
Input/output contract
Use a table for filename, format, required content, sensitivity level, and retention policy. Define at least meeting.txt, config.json, and summary.md, and give a fully fictional minimal input, configuration, and expected output.
Acceptance and troubleshooting
Include at least four failures: missing file, encoding error, JSON syntax error, and empty output. For each, state an observable symptom, diagnostic command, and safe recovery.
Mermaid flowchart
Draw “read → validate → summarize → human confirmation → end.” Clearly state that there are no external side effects before human confirmation.
Sources and change record
Use standard links for external materials and record their retrieval date. The change record states what changed and what was verified; do not write an unprovable “fully usable.”
Quality check
| Dimension | Failing | Passing |
|---|---|---|
| Structure | stacked headings with no order | reader can locate the task by hierarchy |
| Commands | no directory or expectation | commands, output, and placeholders are clearly separate |
| Links | ambiguous or broken | internal paths are clear and external links have descriptions |
| Evidence | expectations written as measurements | executed and unexecuted work are clearly distinct |
| Safety | examples include real data or credentials | only fictional data and explicit dangerous boundaries |
| Rendering | fences and diagram not checked | both editor and Reading View are reviewed |
Real-task acceptance
Ask a reader with no background to answer these questions using only the runbook:
- From which directory do I run it?
- How do I confirm that Python is available?
- What does the input contain, and which data is prohibited?
- What result counts as success?
- Which errors require stopping?
- Will the output be sent automatically?
If the reader needs the author to explain verbally, the runbook is still missing information. Record their questions as document-test results, then revise.
Scoring rules
The total is 20 points, with each item worth 0–2:
- audience, goal, and non-goals are clear;
- prerequisites include verification commands;
- every step states working directory, command, and stop condition;
- input/output contract is checkable;
- expected result and actual verification are separate;
- all four failure types have observable symptoms and safe recovery;
- internal links target real full paths and external links have descriptions;
- Mermaid expresses only the key control flow;
- there is no real sensitive information or destructive command;
- sources date, changes, and unverified items are recorded.
Completion requires at least 16 points and no safety item scored 0. If another reader still needs verbal supplementation, the maximum score is 15.
Knowledge-base self-test
- How are Markdown and a renderer related?
- Why must CommonMark, GFM, and Obsidian extensions not be conflated?
- Why is heading hierarchy more important than font size?
- How do you choose between fenced code and inline code?
- How do you avoid link ambiguity when internal files share a name?
- Why should an external URL not use a wikilink?
- When is a table worse than a list?
- What kind of relationship is Mermaid suitable for expressing?
- How does a document distinguish expected output from actual verification?
- Why does documentation need a safety review too?
Mastery check
- I completed one runbook with metadata, procedures, a table, code fences, links, and Mermaid.
- Every internal link resolves to a real file and every external link has descriptive text.
- I checked layout in Obsidian Editor View and Reading View.
- Another reader completed a paper walkthrough using the runbook.
- I recorded unverified items and did not present sample output as measured evidence.
- The document contains no real credential, sensitive data, or unsafe bulk-delete command.
Previous: Integrated writing practice and Mermaid debugging.
After finishing, compare item by item with the reference answer, then return to the Markdown index.
References
Retrieved: 2026-07-14.