Skip to main content

A Couple of Architectural Approaches: Emergent vs. Documentation-Driven Development

When building projects—especially smaller ones like CLIs—I’ve experimented with various architectural approaches. Two key strategies stand out to me:

Emergent Architecture​

This approach allows the architecture to evolve naturally as you write the code and add features.

Pros:​

  • Flexibility: You’re not locked into a predefined structure, so the architecture grows with the project.
  • Speed: Great for prototyping and iterating quickly.

Cons:​

  • Lack of Clarity: Without a clear plan, it’s easy to lose track of how components interact.
  • Potential Refactoring: As complexity increases, you may need to refactor parts of the architecture to align with new requirements.

Documentation-Driven Development (DDD)​

These days, I prefer Documentation-Driven Development: defining functionality through a README or man page before writing a single line of code.

How It Works:​

  1. Write a detailed README or man page describing the functionality, commands, and user experience.
  2. Start coding based on the defined documentation.
  3. Use the README as a reference for testing and feature validation.

Pros:​

  • Clarity: You know exactly what you’re building before you start.
  • Better Communication: Useful for collaborating with others, as the documentation serves as a shared source of truth.
  • Focus: Avoids unnecessary scope creep by sticking to the predefined functionality.

Cons:​

  • Initial Overhead: Writing documentation upfront can feel slower compared to jumping straight into coding.

Choosing the Right Approach​

For small, experimental projects, emergent architecture can be effective. For projects that require a more structured approach or will be shared with others, documentation-driven development provides clarity and focus from the start.