# documenter

> Guide for documenting system concepts (factories, seeding, patterns, architecture decisions) with focus on human-readable explanations over code. Reference code files instead of embedding. Use when documenting backend systems, data models, architectural patterns, or any non-component technical concepts.

- Author: jayarjo
- Repository: codentist-ai/codey
- Version: 20260126114131
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/codentist-ai/codey
- Web: https://mule.run/skillshub/@@codentist-ai/codey~documenter:20260126114131

---

---
name: documenter
description: Guide for documenting system concepts (factories, seeding, patterns, architecture decisions) with focus on human-readable explanations over code. Reference code files instead of embedding. Use when documenting backend systems, data models, architectural patterns, or any non-component technical concepts.
---

# Documenter

## Overview

Create comprehensive documentation for system concepts like factories, seeding, architecture patterns, and technical decisions. The goal is **exhaustive but sane** documentation - complete coverage without unnecessary fragmentation.

This skill differs from `component-documenter` which focuses on UI component documentation with props, hooks, and visual rendering. Use this skill for backend systems, data flows, architectural decisions, and non-visual technical concepts.

## Documentation Structure

### Folder Organization

When documenting a complex system, create a dedicated folder under `docs/`:

```
docs/
  [topic]/
    README.md              # Index with overview and navigation
    architecture.md        # System design, key decisions
    data-model.md         # Schema, types, relationships
    operations.md         # Queries, workflows, configuration (consolidated)
    [topic-specific].md   # Domain-specific docs as needed
```

### What to Consolidate vs Separate

**Consolidate into single files:**
- Small related topics (e.g., queries + performance + security → `operations.md`)
- Related use cases into one file
- Supporting details into main files

**Keep separate:**
- Substantial standalone topics (architecture, data model)
- Historical context (migration history)
- Practical references (testing guide)
- Future work and open questions

## Content Guidelines

### 1. Describe with Words, Link to Source

**Do this:**
> The [`UserFactory`](https://github.com/org/repo/blob/abc123/apps/api/prisma/factories/user.factory.ts#L15-L45) generates test users with randomized but realistic data. It uses Faker for name generation and creates associated profile records automatically.

**Not this:**
```typescript
// 50 lines of factory code copied here
```

### 2. Reference Code with GitHub Permalinks

When referencing code, **always generate clickable GitHub permalinks** that point to the exact commit, so links remain stable over time.

**Permalink format:**
```
https://github.com/[ORG]/[REPO]/blob/[COMMIT_SHA]/[FILE_PATH]#L[START]-L[END]
```

**How to generate:**
1. Get commit SHA: `git rev-parse HEAD`
2. Get repo root: `git rev-parse --show-toplevel`
3. Get GitHub URL from origin: `git remote get-url origin`
4. Normalize URL formats:
   - `git@github.com:ORG/REPO.git` → `https://github.com/ORG/REPO`
   - `https://github.com/ORG/REPO.git` → `https://github.com/ORG/REPO`

**Line number anchors:**
- Single line: `#L42`
- Line range: `#L42-L57`

**For Markdown files:** Add `?plain=1` to show line numbers:
```
.../blob/[SHA]/path/to/file.md?plain=1#L10-L20
```

**Markdown link format:**
```markdown
[src/path/to/file.ts:L10-L25](https://github.com/org/repo/blob/abc123/src/path/to/file.ts#L10-L25)
```

**Example in documentation:**
> The request validation happens in [`src/utils/validation.ts:L12-L35`](https://github.com/org/repo/blob/abc123/src/utils/validation.ts#L12-L35). It checks file types and enforces the 18-image limit.

### 3. Small Code Snippets for Illustration

When a concept needs illustration, use 1-15 line focused snippets:

```typescript
// Key pattern: Factory with relations
await factory.user.create({
  include: { profile: true, preferences: true }
});
```

### 4. Explain the "Why"

Document not just what exists, but why decisions were made:
- Why this pattern over alternatives?
- What constraints drove the design?
- What are the tradeoffs?

### 5. Document Gaps and Limitations

Be explicit about what's missing or incomplete:
- Known issues
- Planned improvements
- Temporary workarounds

## File Templates

See `references/documentation-templates.md` for copyable templates:
- README.md (index file)
- architecture.md
- data-model.md
- operations.md
- Generic concept doc

## Anti-Patterns

### Don't Copy Entire Source Files

Large code blocks become stale. Instead, describe the code and reference the file path.

### Don't Fragment Unnecessarily

One file with 5 sections is better than 5 tiny files. Consolidate related topics.

### Don't Document Obvious Code

If the code is self-explanatory, reference it. Document the non-obvious parts: design decisions, edge cases, integration points.

### Don't Skip the Index

Every documentation folder needs a README.md that provides overview and navigation.

### Don't Duplicate Information

Single source of truth. Reference other docs instead of copying content.

## Quick Reference Checklist

When creating documentation for a system:

- [ ] Create folder under `docs/[topic]/`
- [ ] Write README.md as index
- [ ] Identify 3-6 substantial topics to document
- [ ] Consolidate small topics into combined files
- [ ] Describe concepts in words, link to source with GitHub permalinks
- [ ] Use commit SHA in permalinks (not branch names)
- [ ] Include the "why" behind decisions
- [ ] Document gaps and limitations
- [ ] Use kebab-case for file names