Skip to content

Organize the project documentation

Status: planning. No full documentation move has been started.

Goal

Make it easy to find the next task, see what is done, and read only the details needed for one topic. Keep the history and evidence available without making it the first thing people have to read.

The current docs folder has 30 top-level files. It also contains old plans, current guidance, test records, inventories and recovery material. Some older documents are hundreds of lines long.

Proposed layout

docs/
  index.md                     Start here
  agent-work-instructions.md   Project rules for an AI assistant
  playable-game-roadmap.md     Short milestones and links to tasks
  tasks/
    README.md                  Task list and status guide
    active/                    Work in progress, including blocked work
    future/                    Ideas and approved work not started
    done/                      Finished tasks with results and limits
  testing/                     Test lists and results by topic
  guides/                       Current instructions and system references
  archive/                      Older plans, reports and recovery material

This tree is a direction, not a list of moves already made. Keep the two existing root instruction and roadmap paths working because they are used by project instructions and existing links. The exact home for current contracts, data inventories and development setup guides will be decided during the inventory step.

Task documents

Each document covers one outcome, such as gamepad re-detection or clearer ability definitions. A milestone groups related tasks through links; it does not repeat all their details. A large task can link to smaller tasks if that makes the work easier to follow.

Keep each task short and use these sections only when useful:

  1. Status: planned, in progress, blocked or done.
  2. Goal: the result the task should achieve.
  3. To do: a short checklist, with completed items marked.
  4. Test and result: what was actually checked, what remains open, and a link to the relevant test list.
  5. Notes or decisions: only details needed to carry out the task.

Use active/ for work underway, including a blocked task; state the blocker inside the file. Use future/ for work not started. Move a task to done/ only after its agreed work is finished, and state any separate remaining work or test limits. Do not mark a task done just because part of it passed.

Use clear, descriptive lowercase file names with hyphens, such as gamepad-redetection.md. Split a document when it is hard to navigate or covers different outcomes; do not split merely to meet a line count. Do not make one task file per ability unless there is a specific reason.

Where information belongs

  • The roadmap owns milestone order and links to task files.
  • Each task owns its goal, checklist, decisions and current status.
  • The existing test lists own detailed test results. A task links to them and gives only a short result.
  • Current guides explain how a system works or how to use it. Historical records keep their original context and are clearly marked as historical.
  • Data inventories and recovery archives remain intact. An inventory entry does not by itself mean a feature is available or tested.

Avoid copying the same checklist into several files. A result should say who tested it, what was checked and what remains uncertain. The owner's manual ability results stay separate from automated checks.

Migration plan

  1. Inventory: identify each existing document as current guidance, active or future work, test evidence, reference data, history or recovery material. Note uncertain cases instead of guessing.
  2. Set up the front page: make the documentation index and task list the easy starting points. Keep the roadmap compact and link milestones to focused tasks.
  3. Move work in small groups: start with the saved ability-definition proposal and clearly identified tasks. Split large current plans by outcome, keeping decisions and unfinished work. Carry forward the owner's preference to test further abilities manually.
  4. Organize guides and history: move or label old material only after checking its purpose. Preserve original records, data files, recovery material and their limits. Do not treat older reports as proof of current behavior.
  5. Fix navigation: update internal links and leave a short pointer at an old path when it is used by project instructions or likely to be needed by existing chats. Avoid long chains of pointers.
  6. Verify: check local links, compare the task list with the roadmap, and verify that moved history and inventories are intact. Check that every task has one clear status and that blocked and unfinished work remains visible.

This is a documentation task. It does not require testing real stages, changing gameplay, or modifying player saves. Unity checks are needed only if a later documentation change also changes Unity content or code.