| name | walkeros-writing-documentation |
| description | - Creating a new package README Use when this capability is needed. |
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
Documentation Types
Where Content Belongs
| Type | Purpose | Audience |
|---|
| Package README | Installation, basic usage, API reference | Package users |
| Website docs | Guides, integration examples, detailed config | Integrators |
| Skills | Process knowledge, workflows | AI assistants, contributors |
Divio Documentation Types
Keep these separate - don't mix tutorials with reference:
| Type | Purpose | User State |
|---|
| Tutorial | Learning | Studying, beginner |
| How-To Guide | Problem-solving | Working, knows what they need |
| Reference | Information lookup | Working, needs facts |
| Explanation | Understanding | Studying, needs context |
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:
Red Flags
| Red Flag | What It Indicates |
|---|
| API name not in package exports | Hallucinated or outdated API |
| Import path doesn't match package.json | Wrong package reference |
| Event name with underscore | Wrong format (should be space) |
| No imports shown | Context missing, harder to validate |
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:
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
| Rule | Do | Don't |
|---|
| Describe capabilities | "Supports SA key, ADC, and custom client" | "Use a SA key file when outside GCP" |
| Reference schemas/examples | "See settings.projectId in the schema" | Repeat what the schema description says |
| Explain why behind defaults | "Defaults to EU location; override via location" | "Set location to US" |
| Flag non-obvious interactions | "When snakeCase: true, all data keys transform before send" | Describe obvious behavior |
| Symptoms → causes | "Empty table? Check projectId and dataset existence" | Step-by-step fix instructions |
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
Export Pattern
import type { Hints } from '@walkeros/core';
export const hints: Hints = {
'auth-methods': {
text: 'Supports three auth methods: ...',
code: [{ lang: 'json', code: '{ "settings": { ... } }' }],
},
};
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
Content
AI Readability
Consistency
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
| Name | Type | Description | Required | Default |
|---|
Examples
Basic
[Simple example]
Advanced: Custom Mapping
[Complex example]
Type Definitions
See src/types.ts for TypeScript interfaces.
Related
### 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
Installation
```bash
npm install @walkeros/[package]
```
Configuration
Next Steps
---
## 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
- Verify examples exist in
apps/quickstart/ or create them first
- Write README using template above
- Write website doc using MDX template
- Run quality checklist
- Verify all code examples against Tier 1-3 sources
For Documentation Updates
- Identify issue priority using matrix above
- Check current state against source of truth
- Make minimal changes - don't over-engineer
- Verify examples still compile
- Run quality checklist
Related Skills
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
