Public documentation for governed AI labor
SDKs/Governance/Connectors
Arx / Docs / Engineer-Level Documentation: Organization Guide

Documentation

Engineer-Level Documentation: Organization Guide

Project-Agent / ENGINEER_DOCUMENTATION_GUIDE.md

Project-Agent repo-root ENGINEER_DOCUMENTATION_GUIDE.md

Best Practices for Technical Documentation

---

Documentation Hierarchy

`` docs/ ├── README.md # Entry point with quick links ├── QUICK_START.md # 5-min setup for new developers ├── ARCHITECTURE.md # System design, data flow, decisions ├── INSTALLATION.md # Detailed setup instructions ├── API_REFERENCE.md # Complete API documentation ├── GUIDES/ # Feature-focused guides │ ├── authentication.md │ ├── policy-configuration.md │ ├── deployment.md │ └── troubleshooting.md ├── EXAMPLES/ # Working code examples │ ├── python-client-usage.md │ ├── api-integration.md │ └── policy-engine-example.md ├── CONTRIBUTING.md # Development workflow └── CHANGELOG.md # Version history ``

---

1. Entry Point: README.md

Purpose: First thing developers see. Get them productive in 2 minutes.

Structure: ```markdown

Project Name

[One-line description]

Quick Start

```bash

Copy-paste commands only

npm install npm run dev ```

What is This?

[3-4 sentence explanation with links to deeper docs]

Key Features

  • Feature 1
  • Feature 2
  • Feature 3

Documentation

Support

[Links to issues, discussions, slack] ```

---

2. Quick Start Guide

Purpose: Get a developer from zero to "hello world" in 5 minutes.

Structure: ```markdown

Quick Start

Prerequisites

  • Language version (Python 3.11+)
  • Required tools (Docker, Node, etc.)
  • OS notes (if any)

Installation

```bash

Minimal setup to run

git clone ... cd ... npm install ```

Your First Program

```python

Paste this and it works

from agentvault import ARXClient

async def main(): async with ARXClient() as client: result = await client.execute(...) print(result)

Run: python example.py

```

Next Steps

```

---

3. Architecture Document

Purpose: Help engineers understand how things fit together.

Structure: ```markdown

Architecture

System Design

[Diagram or ASCII art showing components]

Core Concepts

Concept 1

  • What it is (1 sentence)
  • Why it exists
  • How it connects to other concepts

Concept 2

...

Data Flow

[Show request → processing → response]

Key Design Decisions

| Decision | Rationale | Trade-offs | |----------|-----------|-----------| | Async-first | Concurrency | More complex code | | Event-based | Loose coupling | Harder to debug |

Extension Points

  • Where to add custom code
  • How to extend functionality
  • Common patterns

Performance Considerations

  • Bottlenecks (if any)
  • Optimization strategies
  • Benchmarks

```

---

4. API Reference

Purpose: Complete specification for every function/endpoint.

Structure: ```markdown

API Reference

Authentication

``python client = ARXClient(api_key="...", api_url="...") ``

Methods

client.execute()

``python async def execute( connector: str, operation: str, params: Dict[str, Any] ) -> Dict[str, Any]: ``

Description: Execute an operation on a connector.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | connector | str | Yes | Connector name (e.g., "crowdstrike") | | operation | str | Yes | Operation to execute | | params | dict | Yes | Operation parameters |

Returns: Operation result as dictionary

Raises:

  • ARXError - Operation failed
  • ARXPolicyError - Policy blocked operation

Examples: ```python

Simple usage

result = await client.execute("crowdstrike", "detections:read", { "limit": 10 })

With error handling

try: result = await client.execute(...) except ARXPolicyError as e: print(f"Policy violation: {e.policy_name}") ```

See Also:

```

---

5. How-To Guides (Feature-Focused)

Purpose: Step-by-step instructions for specific tasks.

Structure: ```markdown

How to [Complete a Task]

Overview

[What this guide covers and why you might need it]

Prerequisites

  • Knowledge assumed
  • Tools required
  • Time estimate

Steps

Step 1: [Do X]

[Explanation of why] ```python

Code example

```

Step 2: [Do Y]

```

Common Issues

  • Problem: Solution
  • Problem: Solution

Next Steps

[What to read next] ```

---

6. Examples (Code-First)

Purpose: Working code developers can copy and adapt.

Pattern: ```markdown

Example: [What You're Building]

Scenario

[What problem this solves]

Code

\\\`python

Complete, runnable example

Can be copy-pasted as-is

\\\`

How It Works

  1. Line 1-5: Does X because...
  2. Line 6-10: Does Y because...

Variations

  • Alternative 1: For when you need X
  • Alternative 2: For when you need Y

See Also

```

---

7. Contributing Guide

Purpose: Help developers contribute code/docs.

Structure: ```markdown

Contributing

Development Setup

``bash git clone ... cd ... npm install npm run dev ``

Project Structure

`` src/ ├── lib/ # Core library code ├── api/ # API endpoints ├── tests/ # Unit & integration tests └── docs/ # Documentation (not code) ``

Workflow

  1. Create feature branch: git checkout -b feature/name
  2. Make changes + write tests
  3. Run tests: npm test
  4. Run linter: npm run lint
  5. Commit: git commit -m "..."
  6. Push: git push origin feature/name
  7. Create PR with description

Code Style

Testing Requirements

  • All features must have tests
  • Coverage minimum: 80%
  • Run: npm test

Documentation Requirements

  • Update README if behavior changes
  • Add examples for new features
  • Update API reference
  • Add entry to CHANGELOG

PR Review

  • Self-review checklist
  • What reviewers will look for
  • How to respond to feedback

```

---

8. Troubleshooting Guide

Purpose: Help solve common problems.

Pattern: ```markdown

Troubleshooting

Problem: [Error Message or Symptom]

Symptoms:

  • What the user sees
  • When it happens

Root Cause: [Why this happens]

Solutions:

Solution 1: [Quick Fix]

```bash

Steps to try

``` Effectiveness: 60% of cases

Solution 2: [Longer Fix]

```bash

Steps to try

``` Effectiveness: 35% of cases

Solution 3: [Nuclear Option]

[Last resort]

Prevention: [How to avoid this in the future]

See Also: [Related issues or guides] ```

---

Documentation Principles for Engineers

1. Code Examples First

  • Real code > prose explanation
  • Examples should be runnable
  • Comments explain WHY, not WHAT

```python

Good: WHY this pattern

We use async/await for concurrency over threads

async with ARXClient() as client: ...

Bad: WHAT it does (obvious from code)

Create an ARX client using async context manager

async with ARXClient() as client: ... ```

2. Progressive Disclosure

`` README (overview) ↓ Quick Start (working example) ↓ API Reference (complete spec) ↓ Architecture (deep dive) ``

Don't explain everything at once.

3. Real Error Messages

When documenting errors, show the actual error:

```markdown

Error: ValueError: API key not provided

What you see: `` Traceback (most recent call last): File "example.py", line 5, in <module> client = ARXClient() ValueError: API key not provided ``

Why: ... ```

4. Copy-Paste Code

Examples should be complete and runnable:

```python

Good: Can be run as-is

import asyncio from agentvault import ARXClient

async def main(): async with ARXClient() as client: result = await client.execute(...) print(result)

asyncio.run(main())

Bad: Fragments that won't run

client = ARXClient() result = client.execute(...) # Missing async/await ```

5. Version Notes

Always specify when things changed:

```markdown

authenticate()

Added in v2.0. Deprecated in v3.0 (use client.auth() instead). ```

6. Cross-References

Link related content:

```markdown See also:

```

---

File Organization Checklist

  • [ ] README.md explains what + why + where to go next
  • [ ] QUICK_START.md gets devs to "hello world" in 5 min
  • [ ] API_REFERENCE.md documents every public function/endpoint
  • [ ] ARCHITECTURE.md explains system design and concepts
  • [ ] guides/ folder covers how-to tasks
  • [ ] examples/ folder has runnable code
  • [ ] CONTRIBUTING.md explains how to modify the project
  • [ ] CHANGELOG.md lists version history
  • [ ] All code examples are tested/runnable
  • [ ] All links in docs are correct
  • [ ] Troubleshooting covers top 5 issues
  • [ ] Search-friendly (good headings, keywords)

---

Tools & Automation

Markdown Linting

``bash npm install -D markdownlint-cli markdownlint docs/**/*.md ``

``bash npm install -D markdown-link-check markdown-link-check docs/**/*.md ``

Documentation Site Generation

```bash

Build HTML from Markdown

node build-docs.js

Serve locally

node serve-docs.js ```

Version Sync

  • Keep docs version consistent with code version
  • Update CHANGELOG with every release
  • Auto-generate API reference from code comments (if possible)

---

Summary: The Doc Stack

| Document | Audience | Purpose | Length | |----------|----------|---------|--------| | README | Everyone | Orientation | 1 page | | QUICK_START | New devs | Get working fast | 1 page | | ARCHITECTURE | Senior engineers | Understand design | 3-5 pages | | API_REFERENCE | All engineers | Complete spec | 10-20 pages | | GUIDES | Specific use cases | How-to instructions | 2-3 pages each | | EXAMPLES | Learners | Working code | 1-2 pages each | | CONTRIBUTING | Contributors | Dev workflow | 2-3 pages | | TROUBLESHOOTING | Everyone | Problem-solving | 3-5 pages | | CHANGELOG | Release managers | Version history | 1 page |

---

Created: 2026-04-24 For: Engineers and Technical Leaders Next: Apply these principles to your project