paulserban.eu

Writing Edition

Paul Serban

Writing, snippets & book notes

Vol. 2026

Documentation as Code: /docs vs /wiki in Software Engineering Project Structures

Treating documentation as a first-class citizen in modern engineering workflows

Introduction

Documentation has historically been treated as an afterthought in software engineering. Code gets version control, testing, and review rigor, while documentation often ends up scattered across tools, outdated, or entirely missing. This gap becomes a bottleneck as systems grow in complexity, teams scale, and onboarding slows down. The concept of documentation as code emerged as a response to this imbalance, advocating that documentation should follow the same engineering discipline as source code.

At the center of this discussion lies a structural decision that many teams overlook: where documentation lives. Should it reside in a /docs directory inside the repository, versioned alongside code? Or should it live in an external /wiki, often managed through platforms like GitHub Wiki, Confluence, or Notion? This is not just a tooling preference-it reflects deeper architectural thinking about ownership, versioning, and long-term maintainability.

This article explores the trade-offs between /docs and /wiki, grounded in real engineering practices, and provides guidance on how to design a documentation strategy that scales with your system.

The Problem: Fragmented and Decaying Documentation

One of the most persistent problems in software systems is documentation drift. Code evolves continuously, but documentation often lags behind. This mismatch leads to outdated instructions, misleading architecture diagrams, and ultimately a loss of trust in documentation itself. When developers stop trusting documentation, they stop using it-and the system becomes harder to understand over time.

The root cause is rarely lack of intent. Most teams want good documentation. The issue is structural. When documentation is separated from the development workflow-stored in external tools or edited without review-it becomes disconnected from the lifecycle of the code it describes. Changes in APIs, infrastructure, or business logic rarely trigger updates in documentation, because there is no enforced coupling.

Another challenge is discoverability and ownership. In wiki-based systems, pages can proliferate without clear structure. Different teams document in different styles, leading to inconsistency. Over time, the wiki becomes a dumping ground rather than a curated knowledge base. This creates cognitive overhead: engineers must evaluate whether a document is still relevant before trusting it.

This is where documentation as code shifts the paradigm. By integrating documentation into the same workflows as code-version control, pull requests, code reviews-you create natural alignment between system evolution and its documentation.

/docs vs /wiki: A Structural Comparison

The /docs and /wiki approaches represent two fundamentally different philosophies of documentation ownership and lifecycle.

/docs: Documentation as Code

The /docs approach places documentation directly inside the repository, typically in Markdown files. This means documentation is versioned alongside the codebase, and changes to documentation go through the same pull request process as code changes.

This model enforces strong coupling between code and documentation. When a feature changes, the expectation is that the corresponding documentation changes in the same commit. This dramatically reduces documentation drift because updates become part of the development workflow, not a separate task.

From a tooling perspective, /docs integrates naturally with static site generators such as Docusaurus, MkDocs, or VitePress. These tools transform Markdown into structured documentation sites, often with versioning support. This enables teams to maintain historical documentation aligned with software releases, which is critical for APIs and SDKs.

However, this approach introduces friction. Non-technical stakeholders may find it harder to contribute, as they need familiarity with Git workflows. Additionally, documentation changes require pull requests, which may slow down quick edits or brainstorming.

/wiki: External and Collaborative Knowledge Base

The /wiki approach separates documentation from the codebase, storing it in an external system. Platforms like GitHub Wiki or Confluence prioritize ease of editing and collaboration, often with rich text editors and minimal barriers to entry.

This makes /wiki particularly effective for organizational knowledge, onboarding guides, or evolving processes. Contributors can quickly update pages without going through a full development workflow. This encourages broader participation, especially from product managers, QA engineers, and other non-developer roles.

The downside is weak coupling with code. Documentation updates are not inherently tied to code changes, which increases the risk of drift. Additionally, versioning is often limited or less precise compared to Git-based systems. This becomes problematic when trying to track how documentation aligns with specific software releases.

In practice, /wiki systems tend to favor flexibility over rigor, while /docs favors consistency and traceability over convenience.

Implementation Patterns for Documentation as Code

Adopting documentation as code is not just about placing Markdown files in a repository. It requires intentional structure, tooling, and workflow integration.

A common pattern is organizing documentation into a /docs directory with clear subdomains such as architecture, APIs, and operations. This creates a predictable structure that scales with the system.

/docs
  /architecture
    system-overview.md
    adr-001-event-driven-architecture.md
  /api
    authentication.md
    rate-limiting.md
  /operations
    deployment.md
    monitoring.md
  /guides
    onboarding.md
    local-development.md

This structure aligns documentation with engineering concerns. Architecture Decision Records (ADRs), for example, provide historical context for design choices and are stored as immutable documents.

To integrate documentation into the workflow, teams often enforce rules in pull requests. For example, any change affecting public APIs or architecture must include corresponding documentation updates. This can be enforced through code review practices or even automated checks.

# Example GitHub Actions check for documentation changes
name: Docs Check

on: [pull_request]

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Ensure docs updated for API changes
        run: |
          if git diff --name-only origin/main | grep -q "src/api"; then
            if ! git diff --name-only origin/main | grep -q "docs/api"; then
              echo "API changes require documentation updates."
              exit 1
            fi
          fi

This pattern enforces alignment between code and documentation, turning documentation into a living artifact rather than static content.

Trade-offs and Pitfalls

Choosing between /docs and /wiki is not binary. Each approach introduces trade-offs that must be evaluated in the context of your team and system.

The /docs approach can become overly rigid if applied dogmatically. Requiring pull requests for every documentation change may discourage contributions, especially for small updates. Teams may also over-engineer documentation pipelines, introducing unnecessary complexity without proportional value.

On the other hand, /wiki systems often degrade over time without strong governance. Without clear ownership and structure, pages become outdated or duplicated. This leads to a paradox where documentation exists but is not trusted, which is arguably worse than having no documentation at all.

Another subtle pitfall is duplication between /docs and /wiki. Some teams attempt a hybrid approach but fail to define boundaries. As a result, the same information exists in multiple places, creating inconsistency. Without clear rules, engineers must guess which source is authoritative.

The key insight is that documentation strategy is an architectural decision. It should reflect system complexity, team structure, and long-term maintainability goals-not just convenience.

Best Practices for a Scalable Documentation Strategy

A pragmatic approach is to combine /docs and /wiki, but with strict separation of concerns. The /docs directory should contain source-of-truth documentation tied directly to the system: APIs, architecture, ADRs, and operational procedures. This content must be versioned and reviewed alongside code.

The /wiki, on the other hand, should serve as a knowledge hub for less rigid content: onboarding guides, team processes, meeting notes, and exploratory ideas. This allows for flexibility without compromising the integrity of system-critical documentation.

Another best practice is to treat documentation ownership explicitly. Each domain of documentation should have a clear owner, typically aligned with team responsibilities. For example, the platform team owns infrastructure docs, while feature teams own API documentation. Ownership reduces ambiguity and ensures accountability.

Automation also plays a key role. Static site generators can transform /docs into navigable documentation portals, while CI pipelines can validate links, enforce structure, and ensure completeness. This reduces manual effort and maintains quality over time.

Finally, documentation should be discoverable. A well-structured /docs directory is only useful if developers can navigate it efficiently. Invest in indexing, search capabilities, and consistent naming conventions to reduce cognitive load.

Key Takeaways

80/20 Insight

The majority of documentation value comes from a small subset of practices:

  1. Keeping documentation in the same repository as code
  2. Updating documentation in the same pull request as code changes
  3. Structuring documentation around architecture and APIs

If you implement just these three consistently, you eliminate most documentation drift and significantly improve system understandability.

Conclusion

The /docs vs /wiki debate is not about tools-it is about engineering discipline. Documentation as code brings rigor, traceability, and alignment with system evolution, but requires intentional workflows and cultural adoption. Wikis provide flexibility and accessibility, but need governance to remain useful.

Strong engineering teams recognize that documentation is part of the system, not an accessory to it. By designing your documentation structure with the same care as your architecture, you create a system that is not only functional, but understandable and maintainable over time.

In the long run, the teams that win are not the ones who write the most documentation-but the ones who keep it alive.

References