167 lines
5.3 KiB
Markdown
167 lines
5.3 KiB
Markdown
# Documentation Index
|
|
|
|
This repository now uses a simple documentation taxonomy so you can quickly tell:
|
|
|
|
- what is current and actionable
|
|
- what is product-facing vs. technical
|
|
- what is historical and should not be treated as source of truth
|
|
|
|
---
|
|
|
|
## Folder Structure
|
|
|
|
### `docs/product/`
|
|
|
|
Current product documents. These are the best starting point when you want to understand:
|
|
|
|
- product positioning
|
|
- MVP scope
|
|
- feature requirements
|
|
- portfolio/presentation story
|
|
|
|
Files:
|
|
|
|
- `job-search-relaunch-prd.md`
|
|
Status: Active
|
|
Type: Product strategy / reboot PRD
|
|
Use when: you want the current product direction and prioritization.
|
|
|
|
- `unified-generation-workflow-prd.md`
|
|
Status: Active
|
|
Type: Feature-level PRD
|
|
Use when: you want the target design for the core generation workflow.
|
|
|
|
### `docs/planning/`
|
|
|
|
Execution-oriented documents. These are for sprint planning, backlog breakdown, and short-term delivery.
|
|
|
|
Files:
|
|
|
|
- `document-status-inventory.md`
|
|
Status: Active
|
|
Type: Documentation audit / implementation mapping
|
|
Use when: you want to know which docs are current, which capabilities are really implemented, and where coding should restart.
|
|
|
|
- `week-1-execution-backlog.md`
|
|
Status: Active
|
|
Type: Sprint / execution planning
|
|
Use when: you want to know what to do first and how to break work into tasks.
|
|
|
|
- `weekend-handoff-2026-04-17.md`
|
|
Status: Active
|
|
Type: Progress handoff / execution snapshot
|
|
Use when: you want to continue work from another machine without reconstructing the latest checkpoint from chat history.
|
|
|
|
### `docs/technical/`
|
|
|
|
Technical reference documents. These are implementation-oriented and may include design guidance or development notes.
|
|
|
|
Files:
|
|
|
|
- `memory-system-dev.md`
|
|
Status: Reference
|
|
Type: Technical design / development guide
|
|
Use when: you work on the memory system or want to study one style of technical design note.
|
|
Note: parts of this document are forward-looking and should be validated against the current codebase before implementation.
|
|
|
|
### `docs/operations/`
|
|
|
|
Runbooks and environment/operations documentation.
|
|
|
|
Files:
|
|
|
|
- `ha-runbook.md`
|
|
Status: Reference
|
|
Type: Operations runbook
|
|
Use when: you work on Docker-based HA deployment, Redis Sentinel, PostgreSQL replication, or backup verification.
|
|
|
|
### `docs/archive/`
|
|
|
|
Historical documents. Keep these for learning or project history, but do not treat them as the current source of truth.
|
|
|
|
Files:
|
|
|
|
- `provider-system-legacy.md`
|
|
Status: Archived
|
|
Type: Historical technical plan
|
|
Why archived: partially outdated; references earlier provider architecture and older app entry naming.
|
|
|
|
- `refactoring-plan-legacy.md`
|
|
Status: Archived
|
|
Type: Historical implementation plan
|
|
Why archived: reflects an earlier refactor phase; some items are completed, some are no longer current priorities.
|
|
|
|
- `stories-split-analysis-legacy.md`
|
|
Status: Archived
|
|
Type: Historical code analysis
|
|
Why archived: tied to a past `stories.py` split effort and no longer represents the current structure.
|
|
|
|
---
|
|
|
|
## Deleted Document
|
|
|
|
The following document was removed instead of archived:
|
|
|
|
- `backend/docs/code_review_report.md`
|
|
Reason: it was a one-off review artifact, not a durable project document, and its main issue was already resolved by the later `0002_add_api_key_to_providers.py` migration.
|
|
|
|
---
|
|
|
|
## Recommended Reading Order
|
|
|
|
If you want to understand the project as a product manager:
|
|
|
|
1. `docs/product/job-search-relaunch-prd.md`
|
|
2. `docs/product/unified-generation-workflow-prd.md`
|
|
3. `docs/planning/document-status-inventory.md`
|
|
4. `docs/planning/week-1-execution-backlog.md`
|
|
5. `docs/planning/weekend-handoff-2026-04-17.md`
|
|
6. `docs/technical/memory-system-dev.md`
|
|
7. `docs/operations/ha-runbook.md`
|
|
|
|
If you want to understand the project as an engineer:
|
|
|
|
1. `docs/planning/document-status-inventory.md`
|
|
2. `docs/product/unified-generation-workflow-prd.md`
|
|
3. `docs/technical/memory-system-dev.md`
|
|
4. `docs/operations/ha-runbook.md`
|
|
5. `docs/archive/*` only when you need historical context
|
|
|
|
---
|
|
|
|
## Documentation Rules Going Forward
|
|
|
|
When adding a new document, place it using these rules:
|
|
|
|
- Put it in `docs/product/` if it explains what should be built and why.
|
|
- Put it in `docs/planning/` if it explains when or in what order work should happen.
|
|
- Put it in `docs/technical/` if it explains how something works or should be implemented.
|
|
- Put it in `docs/operations/` if it is about deployment, environments, runbooks, or maintenance.
|
|
- Put it in `docs/archive/` if it is historically useful but no longer current.
|
|
|
|
Delete a document only when all three are true:
|
|
|
|
- it is a one-off artifact
|
|
- it is not a reusable reference
|
|
- its key information is either obsolete or already captured elsewhere
|
|
|
|
Archive instead of deleting when:
|
|
|
|
- the document shows project history
|
|
- the document may still help future debugging or learning
|
|
- you are not fully sure whether it is still valuable
|
|
|
|
---
|
|
|
|
## PM Learning Note
|
|
|
|
A good documentation system helps you think clearly:
|
|
|
|
- `product` tells you what problem you are solving
|
|
- `planning` tells you what to do next
|
|
- `technical` tells you how the system works
|
|
- `operations` tells you how to run it
|
|
- `archive` tells you what used to be true
|
|
|
|
That separation is useful not only for this repo, but also as a general PM habit. Many product documents become confusing because they mix all five at once.
|