docs: reorganize tree, restore architecture + research from archive, add Phase 0 reports
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>
This commit is contained in:
@@ -0,0 +1,171 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user