Project documentation

Project Documentation

Overview

Good projects have a paper trail. This skill ensures that completed work gets documented in two complementary ways:

1. Journal entries — What was done, when, and why. A chronological record of decisions and changes.
2. Manuals — How to use, configure, or restart things. A practical reference for the future.

Not every piece of work needs both. A quick bugfix might only need a journal entry. A new service deployment needs both. The skill helps you decide.

Announce at start: "Using project-documentation to write up this work."

When to write what

                  ┌─────────────────────────┐
                  │ Significant work done?   │
                  └────────┬────────────────┘
                           │
                    ┌──────▼──────┐
                    │ Journal     │ ← Always, for any non-trivial work
                    │ entry       │
                    └──────┬──────┘
                           │
              ┌────────────▼────────────────┐
              │ Does the work involve:      │
              │ • Commands to run?          │
              │ • Config files to edit?     │
              │ • Services to start/stop?   │
              │ • Multi-step setup?         │
              │ • Things someone would      │
              │   forget in 3 months?       │
              └─────────┬──────────┬────────┘
                    Yes │          │ No
               ┌────────▼──┐      │
               │ Manual     │      │
               │ too        │      │
               └────────────┘      │
                                   │
                            Done ◄─┘

Step 1: Find the docs directory

Look for a docs/ directory in the project root. Within it, look for journal/ and manuals/ subdirectories. If they don't exist, create them.

If the project has no docs/ directory, look for journal/ and manuals/ at the root. Use whatever structure the project already has — don't reorganize without asking.

Step 2: Write the journal entry

Check for an existing related entry

Before creating a new file, scan existing journal entries for one that covers the same topic. The work you just did might be a continuation of earlier work — if so, append to the existing file under a new section header with today's date.

Create or append

Filename pattern: YYYY-MM-DD-short-description.md

Structure:

# Title

**Date:** YYYY-MM-DD

## Objective

One or two sentences: what were we trying to accomplish and why?

## What was done

Describe the work in logical sections. Include:
- Decisions made and the reasoning behind them
- What was tried and didn't work (if relevant)
- Key files changed or created
- Commands run (if notable)

## What's NOT included (and why)

Optional — useful when something was deliberately excluded or deferred.

## Outcome

Brief statement of the result. Link to any PRs, issues, or follow-up work.

Keep it factual and concise. The journal is for someone (including future-you) trying to understand what happened and why. Don't pad it — if the work was simple, the entry should be short.

Appending to an existing entry

When appending to an existing journal file, add a new date-stamped section:

## YYYY-MM-DD — Follow-up title

Description of what was done in this session...

Step 3: Decide if a manual is needed

A manual is needed when the work produced something that someone will need to operate in the future — not just understand (that's the journal's job).

Ask yourself: "If the server rebooted tomorrow, or if I came back to this in 3 months, would I know what commands to run?" If the answer is no, write a manual.

Needs a manual:

• New service or daemon deployed
• Docker containers configured
• CLI tools installed with specific setup
• Cron jobs or scheduled tasks created
• Infrastructure provisioned (Terraform, Ansible, etc.)
• Authentication or secrets configured
• Anything with a "how to restart" procedure

Doesn't need a manual:

• Code refactoring
• Bug fixes (unless the fix involves operational steps)
• Documentation-only changes
• Simple library additions

Step 4: Write or update the manual

Check for an existing manual

Scan manuals/ (or docs/manuals/) for an existing manual covering the same system or tool. Update it rather than creating a duplicate.

Create or update

Filename pattern: descriptive-name.md (not date-prefixed — manuals are living documents)

Structure:

# System/Tool Name

## Overview

What is this, what does it do, and where does it run?

## Prerequisites

What needs to be installed or configured first?

## Configuration

Key config files and their locations. What each setting does.
Don't include actual secrets — reference where they're stored.

## Common operations

### Starting / stopping

Commands to start, stop, restart the service.

### Checking status

How to verify it's running correctly.

### Viewing logs

Where logs are and how to tail them.

## Troubleshooting

Common issues and how to fix them.

Not every section applies to every manual. Use what's relevant, skip what isn't. The goal is practical — someone should be able to follow the manual to get things working without having to reverse-engineer anything.

Updating an existing manual

When updating, preserve the existing structure. Add new sections, update outdated commands or paths, and note what changed at the top:

> **Updated YYYY-MM-DD:** Added section on X, updated Y command.

What good documentation looks like

Journal entries are honest and specific. They record what actually happened, not an idealized version. Include things that went wrong or took longer than expected — that context is valuable.

Manuals are practical and scannable. Someone should be able to find the command they need in under 30 seconds. Use code blocks generously. Keep explanatory text short — the reader is trying to do something, not learn the theory.

Both should be written for someone who has context about the project but wasn't in the room when the work was done.

Common mistakes

Writing a journal entry that's really a manual — If your journal entry is mostly commands and config snippets, you probably need a manual instead (or in addition).

Creating a new file when you should append — Check existing files first. A single coherent document about "email integration" is better than three separate dated entries.

Including secrets in documentation — Reference where secrets are stored (BWS, .env, vault), never include the actual values.

Writing for today instead of tomorrow — The documentation is for future-you who has forgotten everything. Be explicit about paths, versions, and context that seems obvious right now.