Docs Update

Dokumentasjonsoppdatering

Oversikt

Denne skillen hjelper med å holde prosjektdokumentasjonen synkronisert med koden. Den inkluderer et automatisert script for drift-deteksjon og retningslinjer for manuell oppdatering.

Sentrale dokumenter

Automatisk sjekk

Kjør docs_drift.py

# Standard sjekk
python scripts/docs_drift.py

# Med alle detaljer
python scripts/docs_drift.py --verbose

# JSON output (for scripting)
python scripts/docs_drift.py --format json

# CI-modus (exit 1 ved kritisk drift)
python scripts/docs_drift.py --ci

Hva scriptet sjekker

Tolke output

============================================================
  DOCUMENTATION DRIFT REPORT
============================================================

DEPENDENCY VERSIONS
----------------------------------------
  [ADVARSEL] React: dokumentert 18.2, faktisk 19.2.0
                    ↑ Oppdater README.md med ny versjon

FOLDER STRUCTURE
----------------------------------------
  [KRITISK] Dokumentert mappe mangler: src/utils
            ↑ Enten opprett mappen eller fjern fra dokumentasjon

EVENT TYPES
----------------------------------------
  [INFO] Event-type i kode men ikke dokumentert: ny_event_type
         ↑ Vurder å dokumentere i ARCHITECTURE_AND_DATAMODEL.md

Manuell oppdatering

Når oppdatere hva

Sjekkliste før release

1. Kjør automatisk sjekk:

   python scripts/docs_drift.py
   

2. Oppdater "Sist oppdatert"-datoer i dokumenter som er endret

3. Verifiser versjoner:

   • Sjekk at README teknologiversjoner matcher package.json
   • Sjekk at THIRD-PARTY-NOTICES har korrekte versjoner

4. Gjennomgå QUICKSTART:

   • Er oppsettstegene fortsatt korrekte?
   • Er API-endpoints oppdatert?

5. Verifiser arkitekturdokumentasjon:

   • Reflekterer diagrammer faktisk arkitektur?
   • Er alle event-typer dokumentert?

6. Regenerer API-dokumentasjon:

   cd backend && python scripts/generate_openapi.py
   

   • Sjekk at openapi.yaml er oppdatert
   • Verifiser at API.md har eksempler for nye endpoints

Beste praksis

Dokumentasjonsstil

• Bruk norsk for brukerrettet dokumentasjon
• Bruk engelsk for tekniske termer (event types, API endpoints)
• Inkluder dato "Sist oppdatert: YYYY-MM-DD" øverst i dokumenter
• Hold diagrammer oppdatert - ASCII-diagrammer i markdown

Når dokumentere

• Under utvikling: Hold CLAUDE.md oppdatert kontinuerlig
• Ved ferdigstillelse: Oppdater relevante docs/ filer
• Før merge: Kjør python scripts/docs_drift.py
• Ved release: Full dokumentasjonsgjennomgang

Unngå

• Duplisering av informasjon mellom dokumenter
• Utdaterte kodeeksempler
• Hardkodede versjoner som ikke vedlikeholdes
• Dokumentasjon av features som ikke er implementert

Integrasjon med andre verktøy

Sammen med static-analysis

# Komplett sjekk før commit
python scripts/check_drift.py      # Kode-synk
python scripts/docs_drift.py       # Dokumentasjon-synk
npm run lint                       # Kode-kvalitet

CI/CD

# GitHub Actions eksempel
- name: Documentation Check
  run: python scripts/docs_drift.py --ci

Vanlige oppgaver

Oppdatere versjoner etter npm update

1. Kjør npm update
2. Kjør python scripts/docs_drift.py
3. Oppdater README.md teknologitabell
4. Oppdater THIRD-PARTY-NOTICES.md

Legge til ny event-type

1. Definer event i backend/models/events.py
2. Dokumenter i docs/ARCHITECTURE_AND_DATAMODEL.md:
   • Legg til i event-tabellen
   • Beskriv når event brukes
3. Kjør python scripts/docs_drift.py --verbose for å verifisere

Ny mappe i prosjektstruktur

1. Opprett mappen
2. Oppdater README.md prosjektstruktur-diagram
3. Oppdater CLAUDE.md hvis relevant for Claude Code kontekst

API-dokumentasjon

Backend API-dokumentasjon følger et to-lags system:

OpenAPI-generatoren

backend/scripts/generate_openapi.py genererer openapi.yaml fra Pydantic-modeller.

# Generer OpenAPI spec
cd backend && python scripts/generate_openapi.py

# Eller med eksplisitt output
python scripts/generate_openapi.py --output docs/openapi.yaml

Workflow for nye API-endpoints

1. Implementer endpoint i backend/routes/*.py
2. Oppdater generatoren - Legg til path i generate_paths() i generate_openapi.py
3. Regenerer spec:

   cd backend && python scripts/generate_openapi.py
   

4. Oppdater API.md - Legg til menneskevennlig dokumentasjon med eksempler
5. Oppdater QUICKSTART.md hvis endpointet er viktig for oppstart

Hva generatoren håndterer

• Schemas fra Pydantic-modeller (automatisk)
• Paths må legges til manuelt i generate_paths()
• Security schemes (CSRF, Magic Link)
• Request/Response eksempler

Synkronisering

OpenAPI-generatoren er source of truth for API-struktur:

Pydantic models → generate_openapi.py → openapi.yaml
                                              ↓
                                    API.md (manuell sync)

Ved drift mellom openapi.yaml og faktiske routes:

1. Sjekk at generate_paths() inkluderer alle routes
2. Kjør generatoren på nytt
3. Oppdater API.md hvis nødvendig

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