arrow_back Back to Guides
Guide Level 02

Project Documentation Guide

How to organize, initialize, and govern technical documentation for projects within the PARA ecosystem.

Project Documentation Guide

This article explains the methodology for organizing and managing document directories for a specific project within the PARA Workspace. To dive deeply into the AI Agent’s algorithm, please see the Workflow /docs Detail.

Core Design Principle: Internal-First

Documentation is the lifeline of project continuity. In the PARA Workspace, documentation adheres rigidly to a Dual-Pathing architecture, underpinned by the Internal-First protocol.

The Internal-First principle mandates: All documentation must be initially drafted and reviewed within a safe, internal workspace silo before being published to the outside world or embedded into source code repositories.

Distinguishing the Two Storage Hubs

A typical project structure looks like this:

Projects/my-awesome-app/
├── docs/               ← (1) WORKSPACE INTERNAL DOCS: Always draft here
│   ├── README.md         ← Doc Index
│   └── architecture.md
│
└── repo/               ← THE SOURCE CODE REPOSITORY
    └── docs/           ← (2) SOURCE CODE DOCS: Tracked, Published documents
        └── architecture.md

1. The docs/ Hub (Internal)

Located at the root level of the project, completely outside of the git-tracked repository directory (repo/).

  • Purpose: Acting as a scratchpad, hosting internal discussions, rough diagrams, and notes strictly dedicated to you and your AI Companion.
  • Privacy Level: Absolute. Git tools will never track this directory. It exists strictly on your local disk and AI memory contexts.
  • Operational Flow: When instructing your AI to “draft docs for feature X”, it defaults to this folder. Here, you are unrestrained: you can write rapidly in your primary language, dropping absolute URLs natively routing to sensitive artifacts/ or sessions/.

2. The repo/docs/ Hub (Public)

Located strictly inside the source code container (repo/).

  • Purpose: Providing the official, polished knowledge base dispatched to remote end-users, code reviewers, or the open-source community.
  • Privacy Level: Public domain. Files committed here will broadcast outward upon GitHub/GitLab remote pushes.
  • Operational Flow: Files manifest here solely following the Publisher routines. Upon migrating documents here, the AI will translate languages (if your repo demands purely English while internal notes were local), and scrub absolute paths/internal logs.

Generating Documents Rapidly

Avoid the boilerplate chore. Hand off initialization logic over to the PARA Agent.

Immediately after cloning a repository or laying down initial software scaffolds, require the AI to write your docs:

/docs new my-awesome-app

(Review full parameter lists at: Workflow /docs).

What Occurs Under the Hood?

Resisting the urge to inject bloated, unhelpful template files, the Agent dynamically parses:

  1. The currently populated source files.
  2. Accurately tagging if the entity is a Web App, a CLI Script, or a Library framework.
  3. Intelligently generating only relevant Markdown files tailored to the tag.
  4. Auto-scaffolding the primary Index: docs/README.md.

The Mandatory Index File (docs/README.md)

You will notice the AI relentlessly insists on constructing docs/README.md. This files acts as your project’s Doc Index. It bridges the gap as a Master Table, logging active documents aligned alongside their last modified dates.

Why is it mandatory? It brutally slashes AI Token consumption overheads. Whenever you boot up (/open) to start the morning, or query the AI for architectural references, the Agent merely parses a tiny 10-line text file. It retrieves the explicit paths of core architecture files directly, completely sidestepping the expensive action of blindly executing ls -R terminal recursions.

Lifecycle: Draft to Publish

The practical documentation cycle for Developers within PARA:

  1. Draft: Trigger /docs new. Aggressively iterate drafts inside docs/architecture.md. Request AI critique.
  2. Review: When the source codebase stabilizes, leverage /docs review. The AI conducts synchronization sweeps—flagging drift between actual running code and legacy documentation data.
  3. Publish: Moments before Pushing commits, initiate /docs publish. AI extracts, distills, potentially translates, and transplants the internal knowledge natively into repo/docs/.
  4. Release: Commit clean files and reset the cycle.

→ Next Layer: Planning & Backlog Guide