Introducing DocuCodes Proposals

Six months from now, when someone asks "why was it built this way?", the answer is already there. Not just the original decision, but how and why things changed along the way.

Every engineering team I've talked to over the past few months has some version of the same story.

Someone writes a design doc. It goes into Notion, or Confluence, or a Google Doc. A few people comment. The team aligns, work begins, and the document is never touched again.

Six months later, a new engineer joins and asks a reasonable question: "why was it built this way?" The answer is a scavenger hunt through Slack threads, dusty wiki pages, and the memory of whoever happened to be in the room.

When I started DocuCodes, I set out to solve this by making the context around code more accessible through walkthroughs of complex code. That work continues, but the more I talked to other software engineers, the clearer it became that the bigger problem is upstream.

After more than twenty conversations with engineering teams, I kept hearing two things. First: technical decisions are scattered across too many tools, none of which are designed to be the long-term home for these decisions. Second: even when teams do have a solid decision-making process, the docs go out-of-date as soon as they're approved. Requirements change. Technical hurdles pop up. The code evolves. The document doesn't. And the gap between what was decided and what was built grows silently.

I recently wrote about The 3 Whys of Software Documentation, a framework for thinking about the different types of "why" behind your code. The biggest and most impactful of the three is what I call the "Big Why": the major technical and business decisions that shape how your codebase evolves. These are the decisions that belong in proposals, design docs, requests for comments (RFCs), and architectural decision records (ADRs). They're also the ones most likely to get lost.

DocuCodes Proposals is the tool I'm building to fix that.

What DocuCodes Proposals Does

DocuCodes Proposals is a dedicated home for your most important technical decisions. Not a wiki. Not a doc buried in a folder. A purpose-built tool where your team writes, reviews, and maintains the decisions that shape your codebase.

Every proposal has structure (a problem statement, a solution, acceptance criteria) but it's flexible enough to fit however your team works. Whether your team writes design docs, RFCs, ADRs, or even product requirements documents (PRDs), the workflow gives you enough guardrails to ensure the essential information is captured without dictating how your team thinks.

Create your proposals from scratch or use the DocuCodes AI Assistant to draft, refine, and strengthen them before they ever go out for review.

Your team reviews proposals the same way they review code: structured feedback, approvals, and a clear path from draft to accepted.

Automatically Up-to-Date

What really separates DocuCodes Proposals is what happens after a proposal is accepted.

Plans drift. That's not a failure of discipline. It's the nature of building software. You learn things as you build. Requirements shift. Edge cases appear. The problem is that when the code drifts from the plan, the proposal never gets updated. You end up with a document that's technically "approved" but doesn't reflect reality.

DocuCodes fixes this by connecting proposals directly to your codebase through the DocuCodes GitHub App integration. When a pull request diverges from a proposal, DocuCodes flags the difference in a PR comment. The author explains the change right in the PR and the proposal is automatically updated to reflect what actually happened. The decision record stays accurate without anyone having to remember to go back and edit a document.

Six months from now, when someone asks "why was it built this way?", the answer is already there. Not just the original decision, but how and why things changed along the way.

What's Next

DocuCodes Proposals is officially open for sign ups starting today. If your team writes design docs, RFCs, or any kind of technical proposal and you're tired of watching them go stale, I'd love to get your hands on it.