Building a Docs-as-Code Workflow With Markdown, Mermaid, and GitHub Actions

[Himashi Meththasena]

Every engineering team starts with noble intentions. A new project launches, and a sleek Notion page or Confluence space is created. Architecture diagrams are drawn, API contracts are detailed, and onboarding guides are carefully written.

Fast forward six months.



The codebase has evolved through dozens of pull requests, hotfixes, and refactors. The documentation, however, remains frozen in time. New developers join the team, follow the setup guide, hit four cryptic setup errors on step two, and realize the docs are a lie.

We’ve all experienced this phenomenon: WikiRot. Traditional static wikis fail because they live completely detached from where engineers actually spend their time: the code.



Here is how we killed our rotting internal wiki and built a sustainable, auto-updating "Code-First" documentation ecosystem that engineers actually maintain.

The Root Cause: Why Traditional Wikis Fail​

Before changing our workflow, we analyzed why our team constantly abandoned Notion and Confluence:

1. Context Switching Friction: Updating a wiki requires opening a browser tab, finding the right page (out of hundreds of stale ones), and manually syncing code changes. Under deadline pressure, documentation is always the first task dropped.
2. Zero Quality Control or CI Validation: There is no pull request process for wikis. Code gets tested, reviewed, and block-checked by CI/CD, while documentation lives in an unversioned void where anyone can break accuracy without feedback.
3. Out-of-Sync Architectural Diagrams: Diagrams drawn in external UI tools become obsolete the moment a microservice endpoint changes or a new message queue is added.

The Solution: The "Code-First Docs" Architecture​

We decided to treat documentation as a first-class citizen of our codebase. If code changes, the documentation changes in the exact same Git commit.



Here are the three pillars we implemented to make Docs-as-Code work at scale:

1. Markdown Co-located with Source Code​

Instead of centralized external wikis, every repository owns its documentation. High-level architecture, setup guides, and troubleshooting runbooks live inside a /docs directory right next to the source code.

├── .github/
│   └── workflows/
│       └── docs-ci.yml
├── docs/
│   ├── architecture.md
│   ├── onboarding.md
│   └── runbooks/
│       └── high-cpu-troubleshooting.md
├── src/
└── README.md

​

2. Automated API and Architecture Diagram Generation​

We stopped manually drawing architecture diagrams and writing API specs by hand. Instead, we generate them programmatically:

• Diagrams-as-Code: We use Mermaid.js embedded directly inside Markdown files. When a system flow changes, engineers update simple text definitions rather than dragging shapes in a UI tool.

```mermaid
sequenceDiagram
    autonumber
    Client->>API Gateway: POST /v1/orders
    API Gateway->>Kafka: Publish OrderCreated Event
    Kafka->>OrderWorker: Consume Event

Moving Beyond Static Annotations​

For APIs, we shifted the burden of maintenance entirely to self-documenting code. Rather than manually describing REST endpoints or gRPC contracts in a browser editor, we leveraged code-level annotations, such as OpenAPI and Swagger for REST services, or Protobuf definitions for gRPC. The beauty of this approach is that the API reference documentation generates itself during the build phase. When a developer adds or modifies an endpoint parameter in the codebase, the documentation updates automatically.

Treating Docs Like Code in CI/CD​

To guarantee quality, we began reviewing documentation in pull requests right alongside production code. We integrated lightweight documentation validation steps directly into our GitHub Actions pipeline. Automated linters immediately catch broken internal links, dead URLs, or bad formatting before code ever hits main.



Once a pull request merges, static site generators like MkDocs Material or Docusaurus automatically pull Markdown files across all our microservices and publish them to a single, beautifully organized, and searchable internal developer portal.

The Measurable Impact​

Transitioning from a neglected wiki to a Code-First Docs model fundamentally reshaped our engineering culture.



The most immediate win was in developer onboarding: new engineers went from struggling for two weeks with outdated setup steps to spinning up their local environments in under three days.



Because documentation now lived right next to the code in pull requests, over 85% of architectural PRs began including matching .md file updates in the exact same commit.



Perhaps best of all, we eliminated lost technical context. Every decision, rationale, and runbook update became fully searchable through git log and git blame, giving engineers immediate insight into why a system was built a certain way without needing to message a senior developer.

Key Takeaways for Engineering Teams​

If you want to kill wiki rot in your organization, meet your developers where they already work. Forcing engineers to jump into an external browser portal guarantees documentation will eventually stall and decay.



By pulling docs into the IDE, enforcing freshness through your CI/CD pipeline, and automating diagram generation directly from source code, you transform documentation from an annoying afterthought into a living asset that scales seamlessly with your codebase.