README — Organizational Conventions

This document describes how documentation is organized in this notes system.

Top-Level Structure

The root node provides basic system information and links to CONTENTS which lists all major projects.

Two-Level Linking Rule

Links follow a strict two-level pattern:

1. CONTENTS → Links ONLY to main project pages (e.g., popit3, gdata-server, ask)

2. Main project pages → Links to their detailed sub-pages (e.g., popit3/architecture, gdata-server/server)

This keeps CONTENTS concise as a directory, while each main project page serves as a hub for its detailed documentation.

Hierarchical Keys

Documents use hierarchical keys with / as a logical separator:

• project — Top-level project overview with links to all detail pages

• project/component — Major components or subsystems

• project/component/aspect — Specific aspects like usage, design, implementation

Navigation Flow

The intended navigation flow is:

1. Root node → CONTENTS (major projects directory)

2. CONTENTS → project (project overview)

3. project → project/component (detailed documentation)

This creates clear separation of concerns and prevents CONTENTS from becoming cluttered with detail-level links.

Granular Documentation

Rather than creating large monolithic documents, prefer many focused nodes:

• Enables specific information retrieval without loading unnecessary context

• Supports fine-grained linking between related concepts

• Makes maintenance easier — update one aspect without affecting others

Common Documentation Aspects

Standard sub-page patterns for technical components:

• component/overview — High-level purpose and architecture

• component/usage — How to use the component

• component/design — Design decisions and rationale

• component/implementation — Implementation details

• component/configuration — Configuration options

• component/troubleshooting — Common issues and solutions

Example Structure

CONTENTS                  # Links to: popit3, gdata-server, ask, etc.
├── popit3                # Links to: popit3/architecture, popit3/database, etc.
│   ├── architecture
│   ├── database
│   └── deployment
├── gdata-server          # Links to: gdata-server/server, gdata-server/notes, etc.
│   ├── server
│   │   ├── api
│   │   └── design
│   └── notes
└── ask                   # Links to: ask/architecture, ask/jobs, etc.
    ├── architecture
    └── jobs
        ├── workflow
        └── schema

Searchable structure over key scanning

When adding or updating notes, also update a parent, index, or worklog note with the searchable terms someone will actually remember: project names, ticket IDs, people, hostnames, dates, status, and next action. Do not rely on listing or scanning note keys as the primary way to rediscover the right note; key scans are a fallback diagnostic, not the navigation model.

version 2