Documentation
Documentation Principles for Engineers
arxsec-site / engineer-docs/best-practices/principles.md
Principle 1: Code Examples First
What: Real code > prose explanation
Write working code that developers can copy and adapt. Avoid explaining what's obvious from reading the code.
Good Example
```python
We use async/await for concurrency over threads
Allows handling many operations simultaneously
async with ARXClient() as client: detections = await client.execute("crowdstrike", "detections:read") ```
Why? The comment explains WHY this pattern was chosen, not what the code does (which is obvious).
Bad Example
```python
Create an ARX client using async context manager
async with ARXClient() as client:
Await the execute method to get detections
detections = await client.execute(...) ```
Why? Comments repeat what the code already shows. They waste time.
---
Principle 2: Progressive Disclosure
What: Start simple, get progressively detailed
Don't explain everything at once. Guide readers through layers of understanding.
`` README (overview, links) ↓ Quick Start (working example) ↓ API Reference (complete spec) ↓ Architecture (deep dive) ``
Good Structure
- README: "What is this in one sentence?"
- Quick Start: "How do I run it?"
- API Reference: "What are all the methods?"
- Architecture: "How does it work internally?"
Bad Structure
Trying to explain everything in the README. Engineers skip it because it's too much.
---
Principle 3: Real Error Messages
What: Show the actual error output, not a paraphrase
When documenting errors, include the real error message. Help people recognize it when they see it.
Good Example
```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: The ARXClient constructor requires an API key. Set it via environment variable or constructor parameter. ```
Bad Example
```markdown
API Key Error
If you forget your API key, you'll get an error message. ```
Why? Engineers won't recognize this when they see it; they don't know what the error looks like.
---
Principle 4: Copy-Paste Code
What: Examples should be complete and runnable
If you show code, it must be code that developers can copy, paste, and run immediately.
Good Example
```python import asyncio from agentvault import ARXClient
async def main(): async with ARXClient() as client: result = await client.execute("crowdstrike", "detections:read", {"limit": 10}) print(result)
asyncio.run(main()) ```
Why? Can be saved to example.py and run immediately: python example.py
Bad Example
``python client = ARXClient() result = client.execute("crowdstrike", "detections:read") # Missing async/await print(result) ``
Why? Won't run. Missing imports, missing async/await, missing asyncio.run().
---
Principle 5: Version Notes
What: Always document when things changed
If something is new, deprecated, or changed, say so clearly.
Good Example
```markdown
authenticate()
Added in v2.0. Deprecated in v3.0 (use client.auth() instead). ```
Why? Engineers know whether this is relevant to their version.
Bad Example
```markdown
authenticate()
Use this method to authenticate. ```
Why? Doesn't tell me when it was added, if it's still used, or what the migration path is.
---
Principle 6: Cross-References
What: Link related content
Help engineers navigate between related pages and sections.
Good Example
```markdown See also:
```
Why? Engineers can dive deeper on topics that interest them.
Bad Example
No links. Engineers have to guess what other docs exist.
---
Summary: Why These Principles Matter
| Principle | Why | Impact | |-----------|-----|--------| | Code First | Engineers learn by example | Faster understanding | | Progressive Disclosure | Don't overwhelm newcomers | Better onboarding | | Real Errors | Engineers recognize problems | Faster problem-solving | | Copy-Paste Code | Minimal friction to try | More adoption | | Version Notes | Engineers know applicability | Less confusion | | Cross-References | Easy navigation | Better discoverability |
The goal: Engineers find what they need quickly, understand it clearly, and get back to coding.