Elbwalker Walkeros Walkeros Writing Documentation

Writing Documentation

When to Use This Skill

• Creating a new package README
• Writing website documentation (MDX)
• Creating or updating skills
• Reviewing documentation for quality
• Documenting Phase 7 of create-destination or create-source

Prerequisites

• understanding-flow - Architecture context
• understanding-events - Event naming rules

Documentation Types

Where Content Belongs

Divio Documentation Types

Keep these separate - don't mix tutorials with reference:

Example Validation (CRITICAL)

The Problem

AI-generated examples can be:

• Syntactically correct but use non-existent APIs
• Plausible-looking but don't match actual exports
• Outdated, referencing deprecated patterns

Source of Truth Hierarchy

TIER 1: apps/quickstart/
  ✓ Tested  ✓ Compiled  ✓ CI-validated
  → USE FOR: All code examples

TIER 2: packages/core/src/eventGenerator.ts
  ✓ Canonical events  ✓ Real data structures
  → USE FOR: Event examples

TIER 3: packages/*/src/index.ts exports
  ✓ Actual public API
  → USE FOR: Verifying API names exist

TIER 4: Package READMEs & Website docs
  ⚠ May contain errors
  → VERIFY against Tier 1-3 before trusting

Validation Checklist

Before publishing ANY code example:

• API exists? Check packages/*/src/index.ts exports
• Pattern validated? Compare against apps/quickstart/
• Events canonical? Use patterns from eventGenerator.ts
• Example compiles? TypeScript check passes
• Imports correct? Package names match actual packages

Red Flags

DRY Patterns

PropertyTable for Configuration

When to use: Any page documenting package configuration with Zod schemas.

import { schemas } from '@walkeros/web-destination-gtag/dev';
<PropertyTable schema={schemas.settings} />;

;

When NOT to use:

• Pages without package configuration
• Reference tables (Logger API, CLI commands)
• Conceptual explanations

Schema Exports (dev.ts)

Every destination/source should export schemas:

// src/dev.ts
export * as schemas from './schemas';
export * as examples from './examples';

Don't Duplicate

• Link to source files instead of copying type definitions
• Reference apps/quickstart/ examples instead of writing from scratch
• Use PropertyTable instead of hardcoded markdown tables

Writing Hints (src/hints.ts)

Hints are the "experienced colleague" layer in walkerOS.json — they tell AI agents when, why, and what to watch out for beyond what schemas and examples convey. Surfaced via MCP package_get. Not human-facing docs.

Audience: AI agents configuring packages on behalf of users.

Core Principle: Expand Awareness, Don't Narrow It

Hints should open up the space of what's possible, not prescribe a single path. An LLM reading hints should think "I have more options than I realized" — not "I must follow these steps exactly."

Writing Rules

Key Naming

• kebab-case, group related hints with prefixes: auth-*, storage-*, query-*, troubleshoot-*
• Keep keys descriptive enough to scan: auth-methods not a1

When to Add Hints

Most packages don't need hints — schemas and examples cover the common case. Add hints when:

• Multiple auth or config strategies exist and it's non-obvious when to use which
• Non-obvious default behaviors need explaining
• Features interact in ways the schema can't express
• Prerequisites outside walkerOS are required
• Common troubleshooting patterns exist

Accuracy Check

Before publishing hints, verify each claim is factually correct. Don't describe features that aren't implemented. Don't assume behavior — confirm it.

Quality Check

• Each hint expands awareness (describes capabilities, not prescriptions)
• Code snippets reference schema fields, not duplicate them
• No hint restates what a schema .describe() already says
• Troubleshooting hints use symptom → cause format
• Hints are atomic — one concept per hint
• Every claim is factually correct against current implementation

Export Pattern

// src/hints.ts
import type { Hints } from '@walkeros/core';

export const hints: Hints = {
  'auth-methods': {
    text: 'Supports three auth methods: ...',
    code: [{ lang: 'json', code: '{ "settings": { ... } }' }],
  },
};

// src/dev.ts
export * as schemas from './schemas';
export * as examples from './examples';
export { hints } from './hints';

Note: hints is a direct export (not * as), because it's already a Record<string, Hint>.

Quality Checklist

Structure

• Follows appropriate Divio type (Tutorial/How-To/Reference/Explanation)
• Code example within first 100 words
• First example under 20 lines
• Uses <details> for advanced content
• Has "Next Steps" or "Related" section

Content

• All event names use "entity action" format with space
• Flow config shown as primary usage pattern
• Examples are complete and copy-pasteable
• Includes imports in code examples

AI Readability

• Clear semantic headers (H2, H3, H4 hierarchy - no skipped levels)
• Tables for structured data
• Links to source of truth TypeScript files
• Static fallback content alongside dynamic components

Consistency

• Uses standard table formats
• Follows package/skill/website templates
• Terminology matches: walkerOS, collector, destination, source
• Headings use sentence case (e.g., "Next steps" not "Next Steps")
• walkerOS.json convention followed (walkerOS field in package.json, buildDev in tsup)

Templates

Package README Template

# @walkeros/[package-name]

[1-sentence description]

[Source Code](link) | [NPM](link) | [Documentation](link)

## Quick Start

```json
{
  "version": 3,
  "flows": {
    "default": {
      "web": {},
      "[sources|destinations]": {
        "[name]": {
          "package": "@walkeros/[package-name]",
          "config": { ... }
        }
      }
    }
  }
}
```

Features

• Feature 1: Brief description
• Feature 2: Brief description

Installation

npm install @walkeros/[package-name]

Configuration Reference

Examples

Basic

[Simple example]

[Complex example]

Type Definitions

See src/types.ts for TypeScript interfaces.

Related

• Documentation

### walkerOS.json

Every package should document its `walkerOS.json` convention in the README:

```json
{
  "walkerOS": { "type": "destination", "platform": "web" }
}
```

The `walkerOS` field is an object with `type` and `platform` metadata describing
the package's role in the walkerOS ecosystem.

### Website Doc Template (MDX)

```mdx
---
title: [Title]
description: [SEO description]
sidebar_position: [N]
---

# [Title]

<PackageLink package="@walkeros/[package]" />

[1-sentence description]

## Quick Start

```json
// Flow config example (<15 lines)

Features

• Feature 1: Description

Installation

Configuration

Next Steps

• Related guide 1

---

## Priority Matrix

### Issue Classification

| Priority | Criteria | Action |
|----------|----------|--------|
| **P0 Critical** | Incorrect examples, wrong APIs, security issues | Fix immediately |
| **P1 High** | Missing PropertyTable, outdated domains, missing sections | Fix soon |
| **P2 Medium** | Inconsistent terminology, skipped headings | Plan to fix |
| **P3 Low** | Style issues, minor wording | Backlog |

---

## Non-Negotiables

### Event Naming

```text

CORRECT: "page view", "product add", "order complete" WRONG: "page_view",
"pageView", "PAGE VIEW"
```

Package References

CORRECT: `@walkeros/collector` (with backticks) WRONG: @walkeros/collector (no
backticks)

Domain References

CORRECT: `www.walkeros.io` or relative paths DO NOT USE: legacy domain
references

Process

For New Package Documentation

1. Verify examples exist in apps/quickstart/ or create them first
2. Write README using template above
3. Write website doc using MDX template
4. Run quality checklist
5. Verify all code examples against Tier 1-3 sources

For Documentation Updates

1. Identify issue priority using matrix above
2. Check current state against source of truth
3. Make minimal changes - don't over-engineer
4. Verify examples still compile
5. Run quality checklist

Related Skills

• walkeros-understanding-flow - Data flow architecture
• walkeros-understanding-events - Event structure and naming

Converted and distributed by TomeVault — claim your Tome and manage your conversions.