Documentation Management

Comprehensive guide for maintaining high-quality, AI-optimized documentation and managing growing codebase history in gnwebsite project.

When to Use This Skill

•User asks to "update documentation" or "organize the changelog"
•Changelog exceeds 1500 lines or 6 months of sessions
•Documentation becomes hard to navigate or retrieve information from
•After major architectural changes or refactors
•When implementing new patterns that should be documented
•Creating or updating technical documentation for AI consumption
•When you hear: "The changelog is too big" or "Make docs more readable"

Core Principles

•AI-Optimized: Write for both humans and AI retrieval systems
•Self-Contained: Each section should work independently
•Explicit Context: Never rely on implicit knowledge or visual cues
•Hierarchical: Clear structure with semantic headings
•Discoverable: Use consistent terminology for semantic search
•Archived: Rotate old changelog entries to maintain readability

Documentation Philosophy (From kapa.ai Best Practices)

How AI Systems Process Documentation

AI agents use Retrieval-Augmented Generation (RAG) which works in three steps:

•Chunking: Documents are divided into smaller, focused sections
•Retrieval: Semantic search finds relevant chunks matching the query
•Generation: LLM uses retrieved chunks to construct answers

Critical implications:

•✅ Sections must be self-contained (can't assume linear reading)
•✅ Context must be explicit (AI can't infer unstated information)
•✅ Related info must be proximate (chunking may separate distant content)
•✅ Terminology must be consistent (enables semantic discoverability)

AI-Friendly Writing Patterns

1. Self-Contained Sections

❌ Context-Dependent (Bad):

markdown

## Updating Webhook URLs

Now change the endpoint to your new URL and save the configuration.

✅ Self-Contained (Good):

markdown

## Updating Django Webhook URLs in gnwebsite

To update webhook endpoints in gnwebsite backend:

1. Navigate to Admin Panel → Webhooks
2. Select the webhook to modify
3. Change endpoint URL field to new address
4. Click "Save" to apply changes

**Location**: `/panel-0911/webhooks/`
**Model**: `jewelry_portfolio.models.WebhookConfig`

Why: AI retrieves sections based on relevance, not document order. Include essential context (what system, where to find, complete steps).

2. Explicit Terminology

❌ Vague References (Bad):

markdown

## Configure Timeouts

Configure custom timeout settings through the admin panel.

✅ Explicit Product/Feature Names (Good):

markdown

## Configure Django API Timeouts in gnwebsite

Configure custom timeout settings for Django REST Framework endpoints:

- **Frontend API calls**: `axios` timeout in `frontend/src/api/index.ts`
- **Backend Gunicorn**: `timeout = 30` in `gunicorn.conf.py`
- **Nginx proxy**: `proxy_read_timeout 30s` in `nginx.conf`

Why: Product-specific terms improve semantic search. "Django" and "gnwebsite" create clear signals for retrieval.

3. Proximate Context

❌ Scattered Information (Bad):

markdown

Authentication tokens expire after 24 hours by default.

The system provides several configuration options for different environments.

When implementing the login flow, ensure you handle this appropriately.

✅ Context Proximity (Good):

markdown

Authentication tokens expire after 24 hours by default. When implementing the 
login flow in gnwebsite, handle token expiration by:

1. Refreshing tokens before 24-hour limit (recommended: 23 hours)
2. Implementing error handling for expired token responses (401 errors)
3. Redirecting to login on token expiration

**Configuration**: `SIMPLE_JWT['ACCESS_TOKEN_LIFETIME']` in `settings.py`

Why: Keeping constraints near implementation guidance ensures they stay together during chunking.

4. Text Equivalents for Visuals

❌ Visual-Dependent (Bad):

markdown

See the diagram below for the complete API workflow:

![Complex flowchart](workflow.png)

Follow these steps to implement the integration.

✅ Text-Based Alternative (Good):

markdown

## gnwebsite OpenAPI Client Generation Workflow

The backend → frontend API sync follows this workflow:

1. **Update Backend**: Modify Django models/serializers/views
2. **Run Tests**: `docker-compose exec backend pytest jewelry_portfolio/ -x`
3. **Generate Schema**: `python manage.py spectacular --file openapi_schema.json`
4. **Generate Client**: `npx @openapitools/openapi-generator-cli generate ...`
5. **Type Check**: `cd frontend && npm run type-check`
6. **Update Services**: Modify service wrappers to use new types
7. **Test Frontend**: `npm run test:run`
8. **Commit Both**: `git add backend/openapi_schema.json frontend/src/api/generated/`

![API workflow diagram](workflow.png)
_Visual representation of the workflow steps above_

Why: AI can't parse images. Text-based workflows are fully discoverable.

5. Error Messages with Context

❌ Generic Troubleshooting (Bad):

markdown

## Connection Problems

If the connection fails, check your network settings.

✅ Specific Error Context (Good):

markdown

## Django Database Connection Errors in gnwebsite

### Error: "django.db.utils.OperationalError: could not connect to server"

**Cause**: PostgreSQL container not running or wrong credentials

**Solution**:
1. Check container status: `docker-compose ps`
2. Restart services: `docker-compose up -d`
3. Verify `DATABASE_URL` in `backend/.env`
4. Check PostgreSQL logs: `docker-compose logs backend`

### Error: "relation does not exist"

**Cause**: Missing migrations

**Solution**:
1. Run migrations: `docker-compose exec backend python manage.py migrate`
2. Verify migration files exist in `backend/jewelry_portfolio/migrations/`

Why: Users search by copying exact error messages. Including them improves discoverability.

6. Hierarchical Structure

✅ Good Information Architecture:

markdown

# Django Authentication (Product Family)
## HttpOnly Cookie JWT Flow (Specific Feature)
### Setup Instructions (Functional Context)
#### Backend Configuration (Component)
#### Frontend Configuration (Component)
### Troubleshooting (Functional Context)
#### Token Expiration Issues (Specific Problem)
#### CORS Configuration (Specific Problem)

Why: URL paths, document titles, and headings provide contextual metadata for retrieval.

Changelog Management

When to Archive

Archive changelog entries when:

•✅ File exceeds 1500 lines (currently at 1879 lines!)
•✅ Sessions older than 6 months
•✅ Historical sessions not referenced in recent work
•✅ Patterns documented in CODEBASE_ESSENTIALS.md

Current status: CODEBASE_CHANGELOG.md has 1879 lines → Archive needed!

Archive Structure

code

docs/changelog/
├── 2026-Q1.md          # Jan-Mar 2026
├── 2025-Q4.md          # Oct-Dec 2025
├── 2025-Q3.md          # Jul-Sep 2025
└── archive-index.md    # Summary of all archived periods

Archive Procedure

Step 1: Create Archive File

bash

# Create quarterly archive
mkdir -p docs/changelog
touch docs/changelog/2026-Q1.md

Step 2: Move Old Sessions

Identify sessions older than 3 months:

bash

# Example: Moving sessions from Oct-Dec 2025 to archive
# Cut from CODEBASE_CHANGELOG.md, paste to docs/changelog/2025-Q4.md

Archive file template:

markdown

# GN Website Changelog - 2025 Q4 (Oct-Dec)

Historical session notes from October-December 2025. For current patterns, see `CODEBASE_ESSENTIALS.md`.

**Archive Period**: October 1 - December 31, 2025
**Total Sessions**: 24
**Major Themes**: Authentication refactor, image optimization, tag system

---

## Session: [Title] (Dec 15, 2025)
[Full session content...]

---

## Session: [Title] (Dec 10, 2025)
[Full session content...]

Step 3: Update Main Changelog Header

markdown

# GN Website Changelog

Historical session notes and detailed changes. For current patterns and invariants, see `CODEBASE_ESSENTIALS.md`.

**Recent Sessions**: Last 3 months (current file)
**Older Sessions**: See [docs/changelog/](docs/changelog/) for quarterly archives

---

[Keep only recent sessions here]

Step 4: Create Archive Index

markdown

# Changelog Archive Index

Historical changelog organized by quarter. For current sessions, see main `CODEBASE_CHANGELOG.md`.

## 2026

### [Q1 (Jan-Mar)](2026-Q1.md)
- Dependency updates skill creation
- WYSIWYG image tracking
- Tag masonry performance optimization
- **Sessions**: 12

## 2025

### [Q4 (Oct-Dec)](2025-Q4.md)
- Privacy policy feature
- Pagination UI implementation
- Authentication refactor
- **Sessions**: 24

### [Q3 (Jul-Sep)](2025-Q3.md)
- Initial project setup
- Django + Vue architecture
- **Sessions**: 18

Archiving Best Practices

What to Archive:

•✅ Sessions older than 3-6 months
•✅ Completed features fully documented elsewhere
•✅ Historical debugging sessions
•✅ Temporary workarounds that were replaced

What NOT to Archive:

•❌ Sessions documenting current patterns
•❌ Recent architectural decisions
•❌ Frequently referenced sessions
•❌ Last 3 months of work

Archive Naming:

•YYYY-QN.md for quarterly archives (e.g., 2026-Q1.md)
•YYYY-MM.md for monthly archives if needed (high activity periods)
•archive-index.md for searchable summary

Documentation Update Workflow

After Implementing Features

•

Update CODEBASE_ESSENTIALS.md if patterns changed:

markdown

## Critical Patterns & Invariants
- **New Pattern**: Description with examples
- Link to reference implementation

•

Add Changelog Entry (MANDATORY for significant changes):

markdown

## Session: [Brief Title] (MMM D, YYYY)

**Goal**: One sentence description

**Changes**:
- [file/path.ts](file/path.ts#L123): What changed and why

**Validation**:
- ✅ Backend tests: X passed
- ✅ Frontend tests: X passed

**Key Learning**: Pattern or gotcha for future reference

•

Create Detailed Docs for complex features:

bash

docs/
├── components/COMPONENT_NAME.md
├── patterns/PATTERN_NAME.md
├── guides/GUIDE_NAME.md
└── incidents/INCIDENT_NAME.md

Documentation File Structure

code

docs/
├── README.md                    # Documentation index
├── architecture/                # System design docs
│   ├── OVERVIEW.md
│   └── DATA_FLOW.md
├── components/                  # Component-specific docs
│   ├── TURBULENT_DISSOLVE_IMAGE.md
│   └── PAGINATION_CONTROLS.md
├── deployment/                  # Deployment guides
│   ├── RAILWAY.md
│   └── PRODUCTION.md
├── guides/                      # How-to guides
│   ├── DEVELOPER_CHECKLIST.md
│   ├── TESTING_STRATEGY.md
│   └── AI_AGENT_PERCEPTION.md
├── incidents/                   # Problem + solution docs
│   └── RAILWAY_DYNAMIC_IMPORT_FAILURE.md
├── patterns/                    # Reusable patterns
│   ├── TWO_STAGE_UPLOAD_TESTING.md
│   └── UNIFIED_IMAGE_ARRAY_REFACTOR.md
├── planning/                    # Planning documents
│   └── FEATURE_ROADMAP.md
├── privacy/                     # Legal/compliance docs
│   └── privacy_and_cookie_policy.md
├── reference/                   # API references
│   └── MAILERLITE_INTEGRATION.md
├── reviews/                     # Code review guidelines
│   └── PULL_REQUEST_TEMPLATE.md
└── changelog/                   # Archived changelogs
    ├── archive-index.md
    ├── 2026-Q1.md
    └── 2025-Q4.md

Documentation Quality Checklist

Before finalizing any documentation:

Structure

• Uses semantic headings (H1 → H2 → H3, no skips)
• Each section is self-contained
• Related information is proximate (same section/paragraph)
• Hierarchical structure reflects logical relationships

Content

• Includes explicit product/feature names (gnwebsite, Django, Vue)
• No reliance on visual layout or positioning
• Error messages quoted exactly with solutions
• Prerequisites stated explicitly (no assumptions)
• Text alternatives for any diagrams/images

Discoverability

• Consistent terminology throughout
• Keywords appear in headings and first paragraph
• Cross-links to related documentation
• Examples include actual code/commands

AI Optimization

• Sections work when read in isolation
• No references like "as mentioned above" without repeating context
• Code examples include language identifiers (python, typescript)
• File paths use absolute paths from project root

Common Documentation Anti-Patterns

❌ Contextual Dependencies

Bad: "Now update the configuration we set up earlier."

Good: "Update the Django settings in backend/gnwebsite_config/settings.py..."

❌ Implicit Knowledge

Bad: "Run the standard Django commands."

Good:

bash

# Apply database migrations
docker-compose exec backend python manage.py migrate

# Collect static files
docker-compose exec backend python manage.py collectstatic --noinput

❌ Visual-Only Information

Bad: Tables with merged cells and complex layouts

Good: Structured lists with repeated context:

markdown

### Django Environment Variables

**DATABASE_URL**
- Purpose: PostgreSQL connection string
- Format: `postgresql://user:pass@host:5432/dbname`
- Required: ✅ Production, ❌ Development (uses SQLite)

**SECRET_KEY**
- Purpose: Django cryptographic signing
- Format: 50+ character random string
- Required: ✅ Always

❌ Scattered Prerequisites

Bad: Prerequisites in introduction, setup in middle, troubleshooting at end

Good: Self-contained sections with inline prerequisites:

markdown

## Setting Up Django Webhooks in gnwebsite

**Prerequisites** (check before proceeding):
- ✅ Django admin access (`/panel-0911/`)
- ✅ Valid HTTPS endpoint with SSL certificate
- ✅ gnwebsite API credentials

**Steps**:
1. Navigate to Admin Panel → Settings → Webhooks
2. ...

Template: Changelog Session Entry

markdown

## Session: [Brief Descriptive Title] (MMM D, YYYY)

**Goal**: One-sentence description of what this session accomplished

**Problem** (if fixing a bug/issue):
Brief description of the problem that required fixing

**Changes**:

- [backend/path/to/file.py](backend/path/to/file.py#L123-L145): **CREATED/UPDATED/FIXED**
  - What changed at this location
  - Why it was necessary
  - Key implementation details

- [frontend/src/path/to/component.vue](frontend/src/path/to/component.vue):
  - What changed
  - Pattern used (link to CODEBASE_ESSENTIALS.md if relevant)

**Validation**:
- ✅ Backend tests: X passed, Y skipped
- ✅ Frontend tests: X passed
- ✅ TypeScript: No errors
- ✅ Manual testing: Description of what was tested

**Key Learning**: 
Pattern, gotcha, or insight that should be remembered for future work. This often becomes a candidate for CODEBASE_ESSENTIALS.md.

**References** (optional):
- Link to related OpenSpec proposals
- Link to detailed documentation in docs/
- Link to related incidents or patterns

Template: Feature Documentation

markdown

# [Feature Name]

Brief overview of what this feature does and why it exists.

## Overview

- **Purpose**: What problem does this solve?
- **Users**: Who uses this feature?
- **Location**: Where in the app is this feature?

## Architecture

### Backend (Django)

**Models**: `jewelry_portfolio.models.FeatureName`
- Fields and relationships
- Key methods and their purpose

**API Endpoints**: `/api/feature/`
- GET: Retrieve feature data
- POST: Create new feature
- PUT/PATCH: Update feature
- DELETE: Remove feature

**Permissions**: `IsAdminOrReadOnly`

### Frontend (Vue 3)

**Views**:
- `FeatureView.vue` - Public view at `/feature`
- `FeatureForm.vue` - Admin editor at `/panel-0911/feature`

**Services**: `featureService.ts`
- API wrapper methods
- Type definitions

**Components**:
- `FeatureCard.vue` - Display component
- `FeatureEditor.vue` - Editing component

## Usage Examples

### Retrieving Feature Data

```typescript
import { featureService } from '@/services/featureService'

const data = await featureService.get()
console.log(data.value)

Admin Updates

typescript

const updated = await featureService.update({
  field: 'new value',
  anotherField: 123
})

Testing

Backend Tests

Location: backend/jewelry_portfolio/test_feature.py

bash

# Run feature tests
docker-compose exec backend pytest jewelry_portfolio/test_feature.py -v

Coverage:

•Model CRUD operations
•API permissions (public/admin)
•Serialization/validation
•Edge cases

Frontend Tests

Location: frontend/tests/feature.test.ts

bash

# Run feature tests
cd frontend && npm run test:run tests/feature.test.ts

Coverage:

•Component rendering
•API integration
•Error handling
•User interactions

Common Patterns

Pattern 1: [Name]

When to use: Description

Example:

python

# Backend example

typescript

// Frontend example

Troubleshooting

Error: "[Exact Error Message]"

Cause: What causes this error

Solution:

•Step-by-step fix
•With commands
•And verification

Documentation Management

When to Use This Skill

Core Principles

Documentation Philosophy (From kapa.ai Best Practices)

How AI Systems Process Documentation

AI-Friendly Writing Patterns

1. Self-Contained Sections

2. Explicit Terminology

3. Proximate Context

4. Text Equivalents for Visuals

5. Error Messages with Context

6. Hierarchical Structure

Changelog Management

When to Archive

Archive Structure

Archive Procedure

Archiving Best Practices

Documentation Update Workflow

After Implementing Features

Documentation File Structure

Documentation Quality Checklist

Structure

Content

Discoverability

AI Optimization

Common Documentation Anti-Patterns

❌ Contextual Dependencies

❌ Implicit Knowledge

❌ Visual-Only Information

❌ Scattered Prerequisites

Template: Changelog Session Entry

Template: Feature Documentation

Admin Updates

Testing

Backend Tests

Frontend Tests

Common Patterns

Pattern 1: [Name]

Troubleshooting

Error: "[Exact Error Message]"

Related Documentation

Create Feature Documentation

Update CODEBASE_ESSENTIALS.md