Skip to main content

How New Tutorials Are Created

This page documents the workflow behind every tutorial in this collection. Each tutorial is generated by an automated pipeline that turns a short topic description into a beginner guide and a deep-dive reference. The rules below are the same rules the pipeline follows.

Overview​

The pipeline runs on a schedule via Claude Cowork. Every morning it scans a drop zone for new markdown files. Each file describes a topic to learn about. For every file it finds, it produces two tutorials — one beginner-friendly and one deep-dive — and files them in a topic folder.

The Drop Zone​

New topic requests live in NewTutorial/drop-zone/ at the root of the source repository. A request is just a markdown file naming the topic and any relevant context. The filename can be terse (e.g. bunch.md, hyperqueue.md); the pipeline figures out the topic name from the content.

After successful generation, the source file is moved to NewTutorial/drop-zone/finished/ so the drop zone stays clean and there is an audit trail of which prompts produced which tutorials.

NewTutorial/drop-zone/ is gitignored — drop-zone files and the archive never appear in the repo or on the docs site. Only this page (how-i-create-new-tutorials.md) is published from NewTutorial/.

Output Location​

Finished tutorials are saved to:

tutorials/{technology-or-app-name}/

The directory name matches the application or technology being covered (Docker, Kubernetes, Apache-NiFi). Convention: title-case with hyphens for multi-word names.

Two Tutorials Per Topic​

For every topic, the pipeline produces two documents:

  1. Beginner Guide — {topic}-beginner-guide.md

    • For someone with no prior experience in the topic
    • Step-by-step instructions, with the why behind each step
    • Includes prerequisites and setup
    • Plain language, jargon defined where unavoidable
    • Suggests diagrams or screenshots where they would help

  2. Deep-Dive Reference — {topic}-deep-dive.md

    • Comprehensive coverage: internals, advanced patterns, edge cases, performance considerations
    • Built to be revisited as an ongoing reference
    • Includes architecture and design rationale

Required Sections​

Every tutorial includes the following sections, scaled to the depth level:

  1. Overview — what the technology is, why it matters, and what the reader will learn
  2. Prerequisites — what to have installed, configured, or understood first
  3. Key Concepts — core ideas, terminology, and mental models
  4. Step-by-Step Instructions — the main walkthrough, in numbered actionable steps
  5. Practical Examples — real-world code, commands, and configuration with explanations
  6. Hands-On Exercises — practice tasks for the reader to reinforce learning
  7. Troubleshooting — common errors, gotchas, and how to resolve them
  8. References — official docs, useful blog posts, related resources
  9. Summary — key takeaways and suggested next steps

The source repository is also managed as an ObsidianMD vault. Tutorials use Obsidian-style wikilinks ([[Page Name]]) so they show up connected in Obsidian's Graph View.

Wikilink rules:

  • Use the bare filename without the .md extension: [[linux-permissions-beginner-guide]], not [[linux-permissions-beginner-guide.md]].

  • Use the bare filename, not a path. Obsidian resolves filenames globally across the vault, so paths are unnecessary.

  • Use [[filename|Display Text]] when the filename alone is not reader-friendly:

    Builds on [[linux-permissions-beginner-guide|Linux permissions]].

When and where to add them:

  1. Before writing, the pipeline searches the vault for related documents using the topic name, related concepts, and common keywords (searching "Docker" might surface links in a Kubernetes tutorial; "Linux" might connect to permissions or NiFi tutorials).
  2. Wikilinks are inserted inline at natural points where a related concept is mentioned.
  3. Each tutorial ends with a Related Tutorials section listing every wikilink, even those already used inline.
  4. When a new tutorial introduces a topic that older tutorials reference, those older tutorials are updated to point back — creating bidirectional connections in the graph.

Note: wikilinks render natively in Obsidian. On the public docs site (Docusaurus), they may appear as plain text. That is expected — the primary graph lives in Obsidian; the docs site is for linear reading.

Style Guidelines​

  • Use fenced code blocks with language identifiers for all commands and code.

  • Prefer practical, real-world examples over abstract ones.

  • Include expected output for commands where possible.

  • For references to other tutorials in the collection, use Obsidian wikilinks ([[filename]]) rather than standard markdown links.

  • Every tutorial begins with a YAML frontmatter block:

    ---
    title: "Topic Name — Beginner's Guide"
    date: YYYY-MM-DD
    difficulty: beginner
    tags: [topic, related-tag, another-tag]
    ---

End-to-End Workflow​

  1. A .md file is dropped into NewTutorial/drop-zone/ describing the topic.
  2. The scheduled task picks it up the next morning.
  3. The task determines the technology/application name from the content.
  4. It creates tutorials/{name}/ if one does not already exist.
  5. It generates {topic}-beginner-guide.md and {topic}-deep-dive.md.
  6. It searches the vault for related tutorials and inserts wikilinks (bidirectionally — updates older tutorials to link back).
  7. On success, it moves the source file to NewTutorial/drop-zone/finished/.