Doc-Oriented Programming: The Future Software Development

In the future, we don’t write code. We write documents, and the code writes itself.
Our job isn’t to type — it’s to think clearly, specify intent, and review intelligently.

The traditional way of building software is no longer the best pratice. With AI tools becoming powerful enough to turn natural language into working software, most of the developers hasn’t realize that we are at the edge of shit.

This shift leads us to Doc-Oriented Programming — a new approach where natural language documents become the primary source of codebase. As a developer you need spend most of your time review rather than build.

1. What Is Doc-Oriented Programming?

Doc-Oriented Programming (DOP) is the philosophy that instead of writing code directly, you write high-fidelity, structured documentation that describes what the system should do. AI tooling and agents take over the rest:

• Code implementation
• Tests
• API specifications
• System design artifacts

Also you need to choose the right AI tooling as your employee to implement your design.

Your main job shifts to writing clear documents and reviewing what AI produces also choose the right AI tooling for your task.

Even if this is still not mature at this stage but with fast development speed of AI tooling. We will reach this point.

2. Role Shift — From Developer to Reviewer

AI is no longer a helper — it’s a builder.

As a developer, your value will be:

• Designing behavior via documents
• Reviewing AI-generated pull requests
• Thinking through edge cases
• Writing tests for edge cases
• Render resources to host your service

Imagine once you write down this line of description in a doc:

Users must now verify their email before logging in.

That change triggers:

• Update to backend logic
• Schema migration
• New test case for unverified logins
• UI prompt for “verify your email”

All generated. All traceable.
Your job? Review the diff and approve.

3. Testing: The New Backbone of Project

In DOP, unit tests become the validation of intent. You don’t just test the code — you test whether the AI interpreted your description correctly.

Since the code is auto-generated, traditional coverage metrics aren’t enough. You’ll want to:

• Test critical business paths(payment, registration…)
• Add unusual scenario tests
• Embed test cases in the doc itself (yes, even test-as-doc!)
• Test edge cases

You might even end up with 120% coverage — because you’re validating interpretation, not just behavior.

4. Example

We need to develop a new blog posting module for our website. We need to tell this

Think of your doc as the source of truth and control. For example:

Step 1: write the documentation

## Module: Blog Publishing Workflow

### Purpose
Manage the lifecycle of a blog post from draft to publication, including human review and audit trail.

### Features
- [ ] Create blog draft (`POST /draft`)
- [ ] Submit draft for review (`POST /draft/{id}/submit`)
- [ ] Review (approve/reject) (`POST /review/{id}/decision`)
- [ ] Publish approved blogs (`POST /publish`)
- [ ] Log all actions in audit trail

### Actors
- **Author**: creates and submits content
- **Reviewer**: approves or rejects posts
- **System**: auto-publishes approved content
### Testing Senerios:
[] make sure the draft always saved after 10 seconds
[] when approve success the blog will be published otherwise throw error.
[] ...

Step 2:

### Pull Request: Initial Implementation of Blog Workflow

**Implemented:**
- Blog draft creation, submission, and review APIs
- State transitions: draft → submitted → approved/rejected
- Role-based access control (Author, Reviewer)
- Post schema and review decision handler
- Unit tests for critical state transitions

**Source:** docs/blog-workflow-spec.md

**To-do:**
- Add audit logging
- Implement automatic publishing after approval

Step 3: Evolving the Doc = Evolving the Codebase

### Features
- [x] Create blog draft (`POST /draft`)
- [x] Submit draft for review (`POST /draft/{id}/submit`)
- [x] Review (approve/reject) (`POST /review/{id}/decision`)
- [x] Publish approved blogs (`POST /publish`)
- [ ] Log all actions in audit trail
+ - [ ] Email notification to author after review
+ - [ ] Optional scheduled publishing (`publishAt`)

5. Do We Need a New Doc Format?

If documentation is the new source of truth, then our current document tools are not enough.

Think about it:

• Markdown is too loose
• JSON/YAML is too rigid
• Prompt engineering is too ad hoc
• Swagger/OpenAPI only covers API surfaces

We need a new kind of “AI-readable design document” that is:

• Human-friendly
• AI-parseable
• Change-traceable
• Scenario-rich
• Extensible across UI/Backend/Test

This might look like a structured Markdown + prompt DSL hybrid — where sections like logic, constraints, edge cases, examples, and data contracts are explicitly defined.

Just like GraphQL redefined APIs, DocLang (let’s call it that) might redefine how we build software with AI.

It would enable:

• Incremental regeneration
• Better change control
• IDE-style validation of docs
• Automated test assertion scaffolding
• Semantic diff on document intent

If we’re going to live in a world where the doc is the software, we better design a format that’s worthy of it.

Final Thoughts: The New Role of the Developer

The more clearly you can describe what you want, the more effective you become in this new world.

AI era is a very valueable oppotunity for all the software engineer to change their life. We need to seize this opportunity as software engineer has a lot of disadvantages. We use AI toolings on daily basis plus we understand how to build a real application rather than use AI tool to build a toy project or POC.

Doc-Oriented Programming is not just a productivity trend — it’s a paradigm shift in how we think, specify, and ship software.

The next generation of Development don’t need us to learn frameworks or best practices as long as you can describe the task and then architect plus review then it is enough.
They’ll master context explanation, scenario modeling, and review code

The sooner you embrace this shift, the faster you rise. I believe the productivity will improve a lot and there will be no BA, Project Manager and Developer they will become the same person.