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>
2.1 KiB
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.