Stop Writing Excel Specs: A Markdown-First Approach to Enterprise Java

Design documents in Enterprise Java often end up trapped in binary silos like Excel or Word, causing them to drift away from the actual code. This pattern shows how to treat Design Docs as source code by using structured Markdown and generative AI.

We've all been there: the architecture team delivers a Detailed Design Document (DDD) to the development team. It’s a 50-page Word file, even worse, a massive Excel spreadsheet with multiple tabs defining Java classes, fields, and validation rules.

By the time you write the first line of code, the document is already outdated.

Binary files are nearly impossible to version, diffing changes is impractical, and copy-pasting definitions into Javadoc is tedious. At enterprise scale, this "Code Drift," where implementation diverges from design becomes a major source of technical debt.

By shifting design documentation to structured Markdown and leveraging generative AI, we can treat documentation exactly like source code. This creates a bridge between the architect’s intent and the developer’s integrated development environment (IDE).

The Problem: The Binary Wall

In traditional Waterfall or hybrid environments, design lives in Office documents (Word/Excel), while code lives in text formats (Java/YAML). Because the formats are incompatible, automation is breaks down. You can't easily "compile" an Excel sheet into a Java POJO, and you certainly can’t unit test a Word doc.

To close this gap, design information needs to be:

1. Text-based (for Git version control).
2. Structured (for machine parsing).
3. Human-readable (for reviews and collaboration).

The solution is Structured Markdown.

The Solution: Markdown as a Data Source

Instead of treating Markdown merely as a way to write README files, we treat it as a structured specification format. By standardizing headers and layout, a Markdown file becomes a consistent, machine-friendly data source that GenAI tools (GitHub, Copilot, ChatGPT, etc.) can parse to generate boilerplate code, diagrams, and even legacy Excel reports for stakeholders.

1. The Directory Structure

To make this approach work, design documents must live alongside the code, mirroring the package structure so they evolve together.

The Pattern:

/project-root
    /src
        /main/java/com/app/backend/RegisteredUser.java
    /design-docs
        /backend
            RegisteredUser.md
            OrderService.md
    /diagrams
        architecture.mermaid

By keeping the .md file in the same repository structure as the .java file, we establish a direct, traceable link between the specification and the implementation.

2. The Structured Spec

The key is to write Markdown as an actual specification, not as a blog post. We use specific headers (such as ## Class Summary, ## Members) that act as hooks for automation tools.

Example: RegisteredUser.md

# RegisteredUser

## Class Summary
Represents a user who has completed the registration process.
Manages user credentials and validation status.

## Members
| Name | Type | Description |
| :--- | :--- | :--- |
| userId | String | Unique identifier for the user. |
| userPassword | String | Encrypted password string. |

## Methods
+ fn isValidUserId(): bool
  - Logic: Returns true if userId length >= 3.
+ fn isValidUserPassword(): bool
  - Logic: Returns true if password length >= 8.

This format is readable to a Product Owner, yet structured enough for an LLM to interpret type definitions and logic constraints. 

Implementation: From Text to Java

Once we express the design in structured Markdown, generative AI can bridge the gap to Java code. In Fujitsu's case study, they utilized a VS Code extension and the OpenAI API to read these Markdown specs and generate initial class scaffolding.

You can replicate this workflow with any GenAI coding assistant. Because the prompt context includes a rigid, predictable structure, hallucination rates drop significantly.

Prompt Context Example:

"Read the following Markdown design doc. Generate a Java class including Javadoc, fields, and validation logic described in the 'Methods' section."

The Generated Output:

package com.app.backend;

/**
 * Represents a user who has completed the registration process.
 * Manages user credentials and validation status.
 */
public class RegisteredUser {

    private String userId;
    private String userPassword;

    public RegisteredUser(String userId, String userPassword) {
        this.userId = userId;
        this.userPassword = userPassword;
    }

    /**
     * Logic: Returns true if userId length >= 3.
     */
    public boolean isValidUserId() {
        return this.userId != null && this.userId.length() >= 3;
    }

    /**
     * Logic: Returns true if password length >= 8.
     */
    public boolean isValidUserPassword() {
        return this.userPassword != null && this.userPassword.length() >= 8;
    }
}

The AI doesn't guess; it implements the specified business rules (>= 3, >= 8) exactly as written. If the design changes, you update the Markdown, and regenerate the code.

Visualizing the Architecture

A common concern when moving away from Excel, Visio, or other diagramming tools is losing the ability to "draw" the system. But now that our design lives in structured text, we can compile it into diagrams.

Using the standardized Markdown headers, we can automatically generate Mermaid.js class diagrams simply by scanning the directory.

Input (Markdown Header):
Class: RegisteredUser depends on Class: UserProfile

#Mermaid Diagram
classDiagram
    class RegisteredUser {
        +String userId
        +String userPassword
        +isValidUserId()
    }
    class UserProfile {
        +String email
    }
    RegisteredUser --> UserProfile

This ensures your architecture diagrams always reflect the current state of the design documents, rather than what the architect drew three months ago.

The "Excel" Requirement

Many enterprises still require an Excel file for official sign-off or for non-technical stakeholders.

But now that the source of truth is structured text (Markdown), generating Excel is trivial. A simple script (or even an AI prompt) can parse the headers and populate a CSV or XLSX template automatically.

• Old Way: Master file is Excel -> Developers manually write Java.
• New Way: Master file is Markdown -> Auto-generate Java and auto-generate Excel for management.

Results and ROI

Shifting to a Markdown-first approach does more than tidy up your repository. In the analyzed case study, teams saw clear productivity gains:

1. 55% faster development: Boilerplate code (classes, tests) was generated directly from the Markdown spec.
2. Reduced communication overhead: AI-assisted translation of Markdown is faster and more accurate than dealing with Excel cells.
3. True diff-ability: Git now shows exactly who changed the business rule, and when in the git commit history. 

Conclusion

Documentation often becomes an afterthought because the tools we use for design (Office) work against the tools we use for development (IDEs). By adopting Markdown as a formal specification language, we pull design work directly into the DevOps pipeline.

So the next time you're asked to write a detailed design, skip the spreadsheet. Open a .md file, define a clear structure, and let the code flow from there.