Project-Agent product-docs engineer-docs/implementation/organization.md

Recommended Directory Structure

`` docs/ ├── README.md # Entry point ├── QUICK_START.md # 5-min setup ├── ARCHITECTURE.md # System design ├── API_REFERENCE.md # Complete API spec ├── CONTRIBUTING.md # Dev workflow ├── CHANGELOG.md # Version history ├── troubleshooting/ │ ├── README.md # Troubleshooting index │ ├── authentication-errors.md │ ├── performance-issues.md │ └── common-problems.md ├── guides/ │ ├── authentication.md │ ├── policy-configuration.md │ ├── deployment.md │ ├── scaling.md │ └── security-hardening.md ├── examples/ │ ├── python-client-usage.md │ ├── api-integration.md │ ├── policy-engine-example.md │ ├── saml-setup.md │ └── scim-provisioning.md ├── styles/ │ └── custom.css # Optional: custom styling ├── SUMMARY.md # GitBook table of contents └── book.json # GitBook configuration ``

---

When to Split vs. Combine

Combine Into One File When:

Under 2,000 words - Still scannable
Single topic - Not covering multiple unrelated things
Low reference traffic - People read it once

Split Into Multiple Files When:

Over 3,000 words - Too long to scan
Multiple distinct topics - People want specific sections
High reference traffic - People need to find specific info quickly

Example: Troubleshooting is better as multiple files (one per issue) rather than one giant file.

---

Naming Conventions

Document Files

Lowercase with hyphens: policy-configuration.md (not PolicyConfiguration.md)
Descriptive: how-to-deploy.md (not deploy.md or deployment.md)
Task-oriented: configuring-saml.md (not saml-overview.md)

Directory Names

Plural for collections: guides/, examples/, troubleshooting/
Singular for concepts: src/, lib/, components/

Entry Points

Always README.md (not index.md or overview.md)
Directories should have README.md (not index.md)

---

Linking Between Documents

Markdown Link Format

``markdown Link text Link text ``

Examples

```markdown

From docs/README.md

Quick Start API Reference Troubleshooting

From docs/guides/authentication.md

Back to Guides See Also: API Reference Example: OAuth Setup ```

Best Practices

Use relative paths (not absolute URLs)
Link to sections with #heading-slug
Link from detailed → general (not the reverse)
Avoid circular links

---

File Organization Checklist

Essential Documents

[ ] README.md exists and is complete
[ ] QUICK_START.md has working setup
[ ] API_REFERENCE.md covers all public APIs
[ ] CONTRIBUTING.md explains dev workflow
[ ] CHANGELOG.md tracks version history

Supporting Documents

[ ] ARCHITECTURE.md explains system design
[ ] guides/ folder has 3-5 how-to guides
[ ] examples/ folder has 3-5 real code examples
[ ] troubleshooting/ folder covers top issues

Documentation Quality

[ ] All code examples are tested and runnable
[ ] All links are correct (no broken links)
[ ] All headings are descriptive
[ ] All sections have clear purpose

GitBook Compatibility

[ ] SUMMARY.md exists with correct structure
[ ] book.json has proper configuration
[ ] All file paths in SUMMARY.md are relative
[ ] No circular links between pages

Metadata & Versioning

[ ] CHANGELOG.md is up to date
[ ] Version numbers follow Semantic Versioning
[ ] Release dates are documented
[ ] Deprecated features are marked

---

Example: Well-Organized Troubleshooting Section

``` troubleshooting/ ├── README.md # Index of all issues │ - Links to all problem sections │ - Quick navigation by category │ ├── authentication-errors.md # Single issue: "API key not found" │ - Exact error message shown │ - Root cause explained │ - 2-3 solutions with effectiveness rates │ - How to prevent next time │ ├── performance-issues.md # Single issue: "Slow queries" │ - When this happens │ - Root cause (no indexing) │ - Solutions (create index, optimize query, scale DB) │ └── common-problems.md # Collection of minor issues

Grouped for brevity
Links to detailed guides
Quick solutions for each

```

Why? Engineers can search for their specific error or browse by category. Each problem is self-contained and complete.

---

Example: Well-Organized Guides Section

`` guides/ ├── README.md # Index of all guides │ - What each guide covers │ - Who it's for │ - Time estimate │ ├── getting-started.md # First guide: basic setup ├── configuration.md # Second guide: configuration ├── deployment.md # Third guide: deploying ├── scaling.md # Advanced: scaling up └── security-hardening.md # Advanced: security ``

Why? Guides progress from beginner → advanced. Each is self-contained but links to related guides.

---

File Size Guidelines

| Document | Target Size | Why | |----------|-------------|-----| | README | 1-2 pages | Entry point; must be scannable | | QUICK_START | 1 page | Get running fast | | ARCHITECTURE | 3-5 pages | Deep but not overwhelming | | API_REFERENCE | 10-20 pages | Comprehensive but scannable | | Each Guide | 2-3 pages | Focused and complete | | Each Example | 1-2 pages | Code + explanation | | Changelog | 1-2 pages | Recent versions only |

Rule of thumb: If it's over 3,000 words, consider splitting it.

---

Version History: Keeping Old Docs

What to do with documentation for old versions?

Option 1: Archive by Version (Recommended for APIs)

`` docs/ ├── v3.0/ │ ├── API_REFERENCE.md │ └── CHANGELOG.md ├── v2.0/ │ └── ... └── v1.0/ └── ... ``

Option 2: Keep Current Only

Update all docs for the latest version. Archive older docs in a separate branch or wiki.

Option 3: Mark Version Clearly