cesnimda
b176a44627
Active docs/ was stub scaffolding while the real docs sat in docs/_archive/. Restore and correct them, and record the Phase 0 work. - docs/architecture/current.md: verified system map (from archived SYSTEM_OVERVIEW, 9 corrections against code). - docs/research/competitors.md: sourced competitor analysis (from archived PRODUCT_RESEARCH, feature matrix corrected). - docs/decisions/ADR-002-job-application-model.md: the Job/JobApplication split. - docs/application-discovery-report.md, docs/implementation-roadmap.md, docs/phase-0-foundation-report.md, docs/career-workspace-branch-assessment.md. - Remove 10 zero-byte placeholder files that advertised content that never existed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
171 lines
2.1 KiB
Markdown
171 lines
2.1 KiB
Markdown
# Jobjakt Documentation Rules
|
|
|
|
## Purpose
|
|
|
|
This document defines how documentation in this repository should be created and maintained.
|
|
|
|
Documentation is considered part of the product.
|
|
|
|
---
|
|
|
|
# Documentation Principles
|
|
|
|
## Source of truth
|
|
|
|
Product decisions:
|
|
|
|
- Product documentation
|
|
- ADRs
|
|
|
|
Technical reality:
|
|
|
|
- Codebase
|
|
- Database
|
|
- Configuration
|
|
|
|
If documentation and code disagree:
|
|
|
|
- Code represents current reality.
|
|
- Documentation represents intended direction.
|
|
|
|
The difference must be documented.
|
|
|
|
---
|
|
|
|
# Document Types
|
|
|
|
## Product Documents
|
|
|
|
Describe:
|
|
|
|
- Why something exists.
|
|
- User problems.
|
|
- Expected behaviour.
|
|
- Business goals.
|
|
|
|
Examples:
|
|
|
|
- Product vision.
|
|
- User journeys.
|
|
- Feature requirements.
|
|
|
|
---
|
|
|
|
## Technical Documents
|
|
|
|
Describe:
|
|
|
|
- How something works.
|
|
- Architecture.
|
|
- Implementation details.
|
|
|
|
Examples:
|
|
|
|
- API documentation.
|
|
- Database models.
|
|
- Services.
|
|
|
|
---
|
|
|
|
## Decision Records
|
|
|
|
Architecture Decision Records explain important choices.
|
|
|
|
Format:
|
|
|
|
|
|
Context
|
|
|
|
Decision
|
|
|
|
Alternatives considered
|
|
|
|
Consequences
|
|
|
|
|
|
---
|
|
|
|
# Required Document Sections
|
|
|
|
Where relevant documents should include:
|
|
|
|
## Purpose
|
|
|
|
Why does this exist?
|
|
|
|
## User Value
|
|
|
|
What problem does this solve?
|
|
|
|
## User Journey
|
|
|
|
How does the user interact with it?
|
|
|
|
## Requirements
|
|
|
|
What must happen?
|
|
|
|
## Non Requirements
|
|
|
|
What should not happen?
|
|
|
|
## Technical Notes
|
|
|
|
Implementation considerations.
|
|
|
|
## Future Considerations
|
|
|
|
Possible expansion.
|
|
|
|
## Open Questions
|
|
|
|
Unknown decisions.
|
|
|
|
---
|
|
|
|
# AI Development Rules
|
|
|
|
AI assistants must:
|
|
|
|
- Read relevant documentation before coding.
|
|
- Analyse existing implementation.
|
|
- Avoid unnecessary rewrites.
|
|
- Preserve existing functionality.
|
|
- Update documentation after significant changes.
|
|
|
|
---
|
|
|
|
# Updating Documentation
|
|
|
|
When implementing features:
|
|
|
|
Update:
|
|
|
|
- Relevant feature documentation.
|
|
- Architecture documentation.
|
|
- ADRs if decisions change.
|
|
|
|
---
|
|
|
|
# Accuracy
|
|
|
|
Never invent:
|
|
|
|
- Existing features.
|
|
- Database fields.
|
|
- APIs.
|
|
- User behaviour.
|
|
|
|
Separate:
|
|
|
|
Fact:
|
|
|
|
Something confirmed in code.
|
|
|
|
Recommendation:
|
|
|
|
Suggested improvement.
|
|
|
|
Future idea:
|
|
|
|
Possible later feature. |