> **Audience**: AI coding assistants and human contributors.
> Read this before writing or expanding any `.md` file in this repository.
---
## Language & Spelling
- **American English only** — `color`, `behavior`, `initialize`, never `colour`, `behaviour`, `initialise`
- Use clear, direct technical prose — no filler, no hedging, no marketing language
- Prefer active voice: "The Blitter copies data" not "Data is copied by the Blitter"
- **Hexadecimal**: Use Motorola syntax (`$DFF180`) for hardware registers and memory addresses, not C-style (`0xDFF180`), unless explicitly within a C code block.
---
## Pre-Flight: Knowledge Base Scan (MANDATORY)
Before writing or expanding any article, you **must**:
1.**Read the root [README.md](README.md)** — it contains the full Documentation Map with every article in the repository. Understand what already exists to avoid duplicating content and to identify cross-linking opportunities.
2.**Scan the section's `README.md`** — know what sibling articles exist in the same folder. Your article should complement, not repeat, adjacent content.
3.**Search for related content** — use grep or file listing to find existing mentions of your topic across the repository. If another article already covers a subtopic in depth, link to it rather than rewriting it.
4.**Check for established patterns** — look at 2–3 exemplary articles in the repository (see "What Makes an Exemplary Article" below) to match style, depth, and structure.
> [!IMPORTANT]
> Every article must exist within the knowledge graph. Orphaned articles are unacceptable. Update the root README's Documentation Map when adding new articles.
---
## Article Structure
Every article must follow this skeleton. Omit sections that genuinely don't apply, but the **Overview** and **Navigation** are mandatory.
#### Type A: Concept Articles (history, chipset, OS subsystem, architectural deep-dives)
These articles answer *why* something exists and *what changed because of it*. The overview should be **scannable and alive** — a reader understands scope in under 10 seconds *and wants to keep reading*.
**Planning checklist** (answer these, then write prose that embeds the answers naturally):
| Question | What it means |
|---|---|
| **What is it?** | Define the thing, its scope, and where it lives. |
| **What was the problem?** | Why does this exist? Concrete pain, not abstract need. |
| **How does it work / how did it evolve?** | Core mechanism or historical arc. |
| **Why does it matter?** | What changed? Numbers, not adjectives. |
**Voice:**
- **Open with a hook.** A contradiction, a surprise, a concrete image. "The Amiga had the best graphics chipset in the world — and a CPU that couldn't do math." Not "Floating-point arithmetic is the computational foundation of..."
- **Write like you're explaining to a smart colleague at a bar.** Short sentences. Concrete nouns (chips, scanlines, frames, hours). No filler.
- **Bold vivid details, not section labels.** Bold `**two and a half video scanlines**`, not `**The problem.**`.
- **Paragraphs tell a story.** Hook → problem → solution arc → punchline. 2–5 sentences each.
- **Every paragraph gets a blank line after it.** Never a monolithic block. If you have 6 sentences about four CPU generations, split them into 2–3 paragraphs — one per phase or per idea. The blank lines are not optional; they are how the reader breathes.
Bad (form-filling):
> **What it is.** Floating-point arithmetic is the computational foundation of 3D rendering...
> **The problem.** The 68000 CPU was integer-only...
> **The solution.** First, Motorola shipped the MC68881...
Good (alive prose — FPU article):
> In 1985, the Amiga had the best graphics chipset in the world — and a CPU that couldn't do math. The 68000 was an integer-only processor: brilliant at moving pixels, helpless at trigonometry. Ask it to compute `sin(0.7)` and it would freeze for **two and a half video scanlines**...
>
> That was the problem the FPU solved. Motorola shipped four generations between 1984 and 1994, each designed under the same brutal constraint: floating-point circuits are **30× more complex** than integer circuits...
---
#### Type B: Reference Articles (register catalogs, file format specs, LVO tables, API listings, error code tables)
These articles exist to be **looked up**, not read cover-to-cover. The overview must be minimal: state what the thing is, where it lives, and get out of the way.
**Template (one paragraph, 2–4 sentences):**
> [Thing] is [definition — one sentence]. It lives in [library / chip / NDK header path / file]. See [cross-link] for the broader context.
**Rules:**
- No hook. No drama. No story arc. The reader came here to look up a register or a flag — don't waste their time.
- State the library name, NDK header, or file extension so the reader knows they're in the right place.
- One paragraph only. No blank-line separation.
- Never stretch to fill space — if 2 sentences cover it, stop.
Good (custom chip registers reference):
> The OCS/ECS custom chip registers occupy the address range `$DFF000–$DFF1FF` and are mapped to the Agnus, Denise, and Paula chips. This article catalogs every register with its address, R/W capability, and bit-field assignments. See the [Copper](copper.md) and [Blitter](blitter.md) articles for programming context.
> AmigaOS error codes are returned in `D0` by Exec and DOS library calls on failure. Negative values indicate warnings (operation completed with caveats); positive values indicate errors (operation failed). This table lists every defined error code from `exec/errors.h` (NDK 3.9). See [Error Handling](../07_dos/error_handling.md) for how to interpret and respond to errors.
- **Hardware Registers**: Documentation must use the following table format, including the R/W (Read/Write/Strobe) capability:
```markdown
| Address | Name | R/W | Description |
|-----------|---------|-----|-------------|
| `$DFF054` | BLTCON0 | W | Blitter control register 0 (minterms, channels) |
```
### 6. API Reference
- Show function prototypes with LVO offsets: `/* LVO -198 */`
- Include practical usage snippets immediately after each prototype
- Group related functions together
### 7. Decision Guides & Comparison Tables
When multiple approaches exist, provide a **decision matrix**:
```markdown
| Criterion | Option A | Option B |
|---|---|---|
| When to use | ... | ... |
| Limitation | ... | ... |
```
### 8. Historical Context & Modern Analogies (MANDATORY for architectural topics)
This is **not optional** for any article covering a fundamental or architectural concept.
**Historical perspective:**
- Include a **competitive landscape** table comparing to contemporary platforms (Atari ST, C64, NES, Mac, PC, arcade hardware)
- Explain what made the Amiga's approach innovative (or not) relative to its era
- Provide **pros/cons analysis** in the context of 1985–1994 hardware constraints
**Modern analogies:**
- Add a **comparison table** mapping Amiga concepts to modern equivalents (macOS Core Animation, Vulkan/Metal, Unity/Unreal, etc.)
- Explain **why** the analogy holds and where it breaks down
- Help modern developers build intuition by connecting unfamiliar retro concepts to things they already know
### 9. Practical Examples
- Every article must include at least one **complete, working code example**
- Examples must compile — no pseudocode unless explicitly marked
- Show the full lifecycle: init → use → cleanup
- Annotate non-obvious lines with inline comments
### 10. When to Use / When NOT to Use
Every API or subsystem article must include explicit guidance on:
- **When to use** — the ideal scenarios, applicability ranges, sweet spots
- **When NOT to use** — situations where a different approach is better, with explanation of why
- **Applicability ranges** — quantify limits (e.g., "works well up to ~20 BOBs; beyond that, custom blitter routines outperform")
### 11. Best Practices & Antipatterns
- **Best practices**: Numbered list of actionable recommendations. Each item should be one line.
- **Antipatterns**: Common bad habits that compile but produce subtle bugs, poor performance, or system instability. Show the antipattern and the correct alternative side by side.
### 12. Pitfalls & Common Mistakes
- Use a dedicated **Pitfalls** section near the end
- Each pitfall gets a numbered subsection with:
- A **bad code example** showing the bug
- An explanation of **why** it fails
- The **correct** version
### 13. Use Cases
Provide real-world use cases that demonstrate practical application:
- What kind of software uses this feature?
- Which well-known Amiga titles or applications relied on it?
- What are the common integration patterns?
### 14. FAQ (when topic resonates)
For topics that commonly generate questions (memory management, blitter programming, display modes), include a short FAQ section addressing the most frequent developer questions.
### 15. References
- NDK header paths
- ADCD 2.1 section references
- Cross-links to related articles in this repository
- External links where authoritative (Apple docs, Commodore manuals)
---
## Formatting Standards
### Memory Maps
- When illustrating memory layouts, stack frames, or hunk structures, use **monospace ASCII box-drawing** (`┌─┐`) rather than Mermaid flowcharts. Mermaid is for logic/state; ASCII boxes are for byte-precise memory layouts.
- **Call Graphs**: Use Mermaid diagrams for call graphs and tables for obfuscation routines/gate mechanisms.
### Tables
- Use tables for structured comparisons, flag lists, register maps, field descriptions
- Always include a header row and separator
- Keep cells concise — one concept per cell
### Code Blocks
- Use fenced code blocks with language tags: ` ```c `, ` ```asm `, ` ```markdown `
- Include NDK source attribution in struct definitions
- Use `/* comment */` for inline annotations in C code
### Mermaid Diagrams
- Use for architecture diagrams, data flow, state machines, and system relationships
- Apply consistent styling: `fill:#e8f4fd,stroke:#2196f3` for DMA/hardware, `fill:#fff9c4,stroke:#f9a825` for coprocessors
- Keep diagrams readable — no more than ~15 nodes per diagram
### Alerts
Use GitHub-style alerts sparingly for critical information:
```markdown
> [!NOTE]
> Background context that aids understanding
> [!WARNING]
> Common mistake that causes data corruption or system crash
```
- **The Chip RAM Alert**: Any API, struct, or hardware register that requires DMA-accessible memory must be highlighted with a `> [!WARNING]` block explicitly stating **Requires Chip RAM**.
### Horizontal Rules
Use `---` to separate major sections. Don't use between subsections.
---
## Depth Expectations
### Shallow (unacceptable)
A struct dump with no context, no explanation of relationships, no examples, no pitfalls. This is a header file, not documentation.
### Adequate
Overview + struct descriptions + one example + references. Functional but not a learning resource.
- Multiple examples covering common and edge cases
- Comprehensive pitfalls with bad/good code pairs
- Performance analysis with quantified costs
- Cross-references to related articles
**Every article in this repository should target "Deep" quality.**
---
## What Makes an Exemplary Article — Key Differentiators
Analysis of the best articles in this repository ([exe_crunchers.md](03_loader_and_exec_format/exe_crunchers.md), [idcmp.md](09_intuition/idcmp.md), [animation.md](08_graphics/animation.md)) reveals consistent patterns that separate deep technical writing from shallow reference stubs:
### 1. The "Why It Exists" Opening
Every great article opens by answering *why* someone should care — not just what the thing is. Compare:
- ✗ *"IDCMP is a messaging system in Intuition."*
- ✓ *"Rather than polling for input, an Amiga application **sleeps** — consuming zero CPU — until Intuition sends a message. This is fundamental to why AmigaOS could multitask smoothly on a 7 MHz 68000 with 512 KB of RAM."*
### 2. Multi-Phase Architecture Diagrams
Great articles don't just describe a process — they break it into **numbered phases** with Mermaid diagrams at each stage. Example: `exe_crunchers.md` walks through 7 discrete steps of the decrunch stub, each with its own code block and explanation. This transforms opaque behavior into a debuggable mental model.
### 3. Named Antipatterns with Bad/Good Pairs
The best articles give antipatterns memorable names:
- "The Kitchen Sink" (requesting all IDCMP flags)
- "The Phantom Gadget" (dereferencing IAddress after ReplyMsg)
- "The Signal Swallower" (checking only one signal source)
Each antipattern shows the **broken code**, explains **why it breaks**, and provides the **corrected version**. This pattern is far more effective than generic warnings.
### 4. Decision Flowcharts
When multiple approaches exist, the best articles include a Mermaid decision flowchart that guides the reader to the correct choice. See IDCMP's "Use IDCMP or Exec MsgPort?" flowchart — it encodes the decision logic visually.
### 5. Use-Case Cookbooks
Beyond toy examples, exemplary articles include a **cookbook** of real-world patterns:
These are copy-paste-ready patterns that solve actual developer problems.
### 6. Quantified Performance Tables
Great articles don't just say "this is slow" — they provide concrete numbers:
- "Mouse movement at fast drag: ~500+ messages/sec — can starve other tasks"
- "3 blitter ops per BOB per frame — expensive at scale"
- "Decompression: ~2–5 seconds on a 7 MHz 68000"
### 7. Cross-Platform Comparison Tables
The best articles include a comparison table that maps Amiga concepts to their equivalents on other platforms (both contemporary and modern). This serves two purposes:
- **Historical context** — shows what was unique about the Amiga
See IDCMP's comparison with Win32/X11/Cocoa/Qt and animation's comparison with Atari ST/C64/NES.
### 8. Memory Safety Checklists
For any API that involves allocation, messaging, or shared resources, exemplary articles include a **risk/cause/prevention** table that acts as a pre-flight checklist.
### 9. The "Impact on FPGA/Emulation" Section
Since this repository targets MiSTer FPGA developers, the best articles note implementation concerns for hardware reproduction: timing-sensitive code, self-modifying code, custom chip register access patterns, cache coherency requirements.
Compare the above with shallow articles that typically lack:
- No "why" — just "what"
- No architecture diagrams
- No decision guides — reader doesn't know when to use the feature
- No pitfalls — reader will hit every bug the hard way
- No antipatterns — reader will write bad code that compiles
- No performance data — reader has no budget intuition
- No cross-platform context — reader can't connect to existing knowledge
- No use-case cookbook — reader can describe the API but can't solve problems with it
---
## Research Methodology
Before writing or expanding an article:
1.**Web research** — Search for real-world usage, developer forum discussions, and existing technical analyses. Ground the article in how practitioners actually used the technology, not just what the API reference says.
2.**Cross-reference NDK headers** — Verify struct layouts, flag values, and LVO offsets against the actual NDK 3.9 headers.
3.**Study real software** — Reference well-known Amiga titles, demos, and applications that use the feature. Cite specific examples when possible.
4.**Verify with hardware documentation** — Cross-check against the Amiga Hardware Reference Manual and custom chip datasheets.
5.**Check modern parallels** — Research whether the concept has modern equivalents; this improves accessibility and reveals design insights.
6.**Scan this repository first** — Follow the Pre-Flight Knowledge Base Scan procedure above before creating any new content.
---
## Content Principles
1.**Hardware grounding** — Always explain which chip, which DMA channel, which register. The Amiga is a hardware platform; software docs without hardware context are incomplete.
2.**No placeholders** — Every code example must be complete enough to compile. Every struct must show real fields from NDK headers. Every register must show the real address.
3.**API Versioning** — Always specify the minimum OS version required for an API (e.g., 'Requires OS 2.0+'). If a struct changed between versions, document the NDK 3.9 version as the modern baseline, and use the `/* V39 */` inline comments exactly as they appear in the headers.
4.**Big-Endian Warning** — Any article dealing with file formats (HUNK, IFF, ADF) or memory structures must explicitly state that the 68000 is **Big-Endian**. Modern developers will almost always read `0x1234` backwards if not reminded.
5.**Honest trade-offs** — When the OS provides an API that most professional software bypassed, say so. When a feature has scaling problems, quantify them. Don't oversell.
6.**Cross-linking** — Every article should link to at least 2–3 related articles. The documentation is a graph, not a list.
7.**Source attribution** — Cite NDK versions, ADCD sections, and ROM Kernel Reference Manual chapters. This is a technical reference, not folklore.
8.**De-abbreviation** — When introducing abbreviations (GEL, BOB, DMA, OCS), always provide the full name on first use and include a full-name column in summary tables.
9.**Real-world grounding** — Every feature must be contextualized with real use cases, applicability ranges, and honest guidance on when to use alternatives. Avoid documenting APIs in a vacuum.
---
## README Index Maintenance
When creating or significantly expanding an article:
- Update the section's `README.md` index table
- Update the root `README.md` Documentation Map if the article is new
- Index entries should be descriptive, not just the topic name:
- ✗ `AnimOb, BOB, VSprite, GEL system`
- ✓ `GEL system deep dive: BOBs, VSprites, AnimObs, hardware foundation, collision detection, double buffering, performance tuning`
