DEV Community

Cover image for Stop Fighting Formatting: Why Documentation Should Be Like Code
Mrakdon
Mrakdon

Posted on

Stop Fighting Formatting: Why Documentation Should Be Like Code

#productivity #devrel #technicalwriting #mrakdon

"Documentation is the roadmap of your code. But when writing it feels like solving a puzzle, you're not building a roadmap—you're fighting a war."

We’ve all been there. You're trying to explain an authentication flow, but half your brainpower is spent wrestling with a diagram tool. You write a JSON example, only to realize the formatting is broken. You draft a section on an API sequence, then spend 20 minutes aligning it in a platform-specific editor.

This is the hidden tax of technical writing.

In this post, we’ll explore how treating documentation like code—through Markdown, Mermaid.js, and write-once publishing—can help you focus on the why and how of your systems, not the formatting.

Key Takeaways

  • Markdown as a universal format: Write in one syntax, publish everywhere.
  • Mermaid.js for live diagrams: Create sequence diagrams in code, no screenshots or exports.
  • Write-once, publish-everywhere: Eliminate platform-specific formatting headaches.
  • Focus on clarity, not alignment: Let tools handle the layout while you explain the logic.

The Struggle: Context Switching Fatigue

Let’s face it: technical documentation is mentally exhausting. Here’s what developers typically do when documenting an API flow:

  1. Open a diagram tool to draw an authentication sequence.
  2. Switch to a text editor to write the JSON payload.
  3. Copy-paste into a blog platform, only to see the formatting break.
  4. Repeat for every new platform or article update.

This context switching isn’t just inefficient—it’s cognitively draining. You lose the flow of explanation, and your readers lose the clarity you intended.

"You’re not just documenting code; you’re documenting a process that’s constantly interrupted."

The "Docs as Code" Philosophy

The solution lies in treating documentation like code: modular, versionable, and deployable. Here’s how Mrakdon makes it work:

Markdown as the Universal Language

Markdown isn’t just for notes. It’s a structured, plain-text format that works across platforms. By writing in Markdown, you:

  • Avoid platform-specific formatting traps.
  • Keep your content in a single, editable file.
  • Enable version control and collaboration via Git.

Mermaid.js for Live Diagrams

Instead of static images, use Mermaid.js to create interactive sequence diagrams directly in your Markdown:

sequenceDiagram
    participant User
    participant AuthServer
    participant API

    User->>AuthServer: Send credentials
    AuthServer-->>User: Return JWT
    User->>API: Request with JWT
    API-->>User: Response
Enter fullscreen mode Exit fullscreen mode

This diagram renders live in any Markdown viewer that supports Mermaid.js. No screenshots, no alignment issues, just clean, explainable logic.

Write Once, Publish Everywhere

Mrakdon automates publishing to Dev.to, Hashnode, and Medium by:

  • Preserving your Markdown formatting.
  • Rendering Mermaid.js diagrams natively.
  • Stripping out platform-specific cruft.

Feature Highlight: Mermaid in Action

Let’s see how a real Mermaid diagram integrates into a technical explanation:

sequenceDiagram
    User->>AuthServer: POST /login with username/password
    AuthServer-->>User: 200 OK with JWT token
    User->>API: GET /data with Authorization: Bearer [JWT]
    API-->>User: 200 OK with JSON payload
Enter fullscreen mode Exit fullscreen mode

This diagram explains the flow without requiring a reader to imagine the steps. It’s also:

  • Editable: Update the flow directly in Markdown.
  • Versionable: Track changes via Git.
  • Portable: Works in any Mermaid-supported platform.

Conclusion: Focus on the Idea, Not the Format

The goal of technical writing isn’t to create pretty formatting—it’s to explain complex systems clearly. By treating documentation like code, you:

  • Reduce cognitive load.
  • Eliminate context switching.
  • Create documentation that evolves with your code.

"Documentation should be the mirror of your codebase—clean, readable, and easy to maintain."

Try Mrakdon today and spend less time fighting tools, and more time explaining why your system works the way it does. Your future self—and your readers—will thank you.

Top comments (0)