i used to write code first, now i write docs first—here’s what changed

I'm a co-founder at Octopipe, a startup building a complex developer tool that automates pipeline creation. We integrate technologies like Airflow, Meltano, Kafka, Spark, Temporal, and manage intricate OAuth flows, database connectors, transformation schemas, and Kubernetes orchestration.

This is the hardest problem I've ever worked on—and I've previously integrated ML-based static analysis into Snyk and co-founded semantic code search tools.

One critical lesson from Octopipe: great developer tools start with great docs. With the rise of code-generation tools powered by large language models (LLMs), docs-first workflows are more crucial than ever, as clear documentation provides the context LLMs need for accurate code generation. Adopting a docs-first workflow changed how we build, think, and ship our software.

The Problem: Why We Start With Docs

As founders with early-stage startup experience, we've seen how development derails without proper documentation:

• Teams build features that miss user needs due to unclear expectations.
• Critical edge cases emerge late in development, forcing costly rewrites.
• Progress halts when team members have different mental models of the solution.

Startups need to move fast, but skipping documentation ultimately slows you down. The good news? With tools like OpenAI's Deep Research, creating comprehensive documentation is now faster and more efficient than ever.

Investing in documentation upfront saves time and frustration later—especially for complex products like ours.

What Is Docs-First Design?

Docs-first means every new feature or change begins and ends with documentation. Docs become your foundation:

• Clearly defining the user interaction (CLI commands, APIs, UI workflows).
• Anticipating edge cases.
• Surfacing unknown unknowns.

Once we’ve documented how a developer will experience a feature, we generate internal design docs, often leveraging LLMs. These technical specs detail exactly how we'll implement the feature:

• Architectural diagrams
• Data flows between services
• Potential pitfalls and open questions

Docs-first works because:

1. Early alignment: You uncover issues before committing code.
2. Collaborative feedback: Docs are easy to share, discuss, and refine.
3. Reduced friction: Unknown unknowns surface early, avoiding late-stage surprises.

Our Iterative Process at Octopipe

1. Start with User Docs: Clearly define user interactions, including authentication, CLI commands, API endpoints, and error handling.
2. Generate Technical Specs Using LLMs: Create detailed technical design documents based on user docs, including diagrams and data flows.
3. Spike for Unknowns: Perform short experiments to clarify complexities highlighted in docs.
4. Iterate Docs: Continuously refine docs until alignment is clear.
5. Setup & Skeleton Code: Scaffold the project structure based on doc clarity.
6. Test Driven by Docs: Derive tests from documented user behaviors.
7. Implement & Review: Code aligns with docs, validated in PR reviews.

Example Prompts for Generating Docs with LLMs

We relied on OpenAI's Deep Research to explore alternative approaches and programmed our prompts for our data engineering domain. Here's an example of the custom prompt we used to guide the generation of our documentation and technical specs:

You are an expert in large-scale real-time data infrastructure. You are helping me with my project.

When answering questions, you can ask me questions first to clarify. This should be a collaborative process.

I might have blind spots that I am not thinking about.

Given the following user documentation:

**PLACEHOLDER:** Insert example user-facing documentation snippet here

Generate a detailed technical specification document that includes:
- Architectural diagrams illustrating data flow and service interactions.
- Classes, methods, or microservices involved.
- Potential edge cases and error-handling strategies.
- Suggested testing scenarios to ensure coverage.

Example: Designing our CLI using Docs-First

We were able to use the docs-first process to design our CLI. The results amazed us: we had a detailed CLI spec in a couple of hours.

We then used this spec as context to Cursor and had a skeleton of the CLI in a few minutes.

Example: Docs Website Before Code

We believe a good developer tool should have excellent documentation. Before writing any code, we built our Docs website.

We invested in "Doc-first" development, which made this possible.

Benefits We've Experienced

• Clarity: Kubernetes orchestration complexities became manageable.
• Faster Iteration: Early decision pivots saved immense engineering time.
• Shared Understanding: Docs fostered alignment and reduced friction.
• Improved UX: Features were intuitive from the outset, designed around docs.
• Easier Onboarding: Clear documentation will streamline new engineer onboarding.

Try Docs-First Yourself

Here's a mini-doc snippet for an OAuth connector:

## Connecting Your Database via OAuth

1. Navigate to "Connectors > Add Connector."
2. Authenticate by clicking "Authorize". Octopipe securely stores tokens.
3. Run `octopipe connector sync` to verify the connection.

*How would you improve this? Any edge cases we missed?*

Starting docs-first for one feature can smooth your engineering process, even if your product isn't as complex as ours.

Why Docs-First Matters More Now

With AI-powered codegen tools, clear documentation isn't just good practice—it's essential. Docs-first workflows provide context to LLMs, making auto-generated code more accurate and reliable.

Docs-first isn't a silver bullet; it requires discipline upfront. But as AI-assisted documentation continues to evolve, it's clearly becoming the future of engineering workflows.