Repository navigation
Replies: 5 comments 2 replies
|
Afaik the intended usage is to have Then the new However there's still no answers about what happens with the PRDs after, whether we keep them for a more detailed implementation record or if it ends up being noise when we're done implementing, especially the file based PRDs (in my case I save mine in |
|
I guess all companies work differently, but from experience, the PRD is a throw-away document and never reflects reality after. Documentation, as @luchillo17 points out, is the source of truth, so once a feature is done and dusted, it's usually cemented by any ADR's taken during that session, with solid documentation on the feature. I've rarely seen a project manager EVER refer back to the PRD as a living document, only for reporting on a macro-level as to what was worked on during any given sprint. |
|
To me the PRD is like an epic. It doesn't mean anything after it's completed, it only describes the work that was actually done at some point in time, which may be useful for things like performance evaluations but not as technical documentation. |
|
Thanks @luchillo17 @AcidRaZor @illeatmyhat all your answers converging on the same thing made it click: PRD is throw-away, long-lived docs are the source oftruth. But there's a structural gap that's still unanswered: where exactly does long-term feature documentation live? "Documentation" is vague, CONTEXT.md is engineering reference, ADRs are architectural decisions. Neither captures the product narrative. For a SaaS product, consulting / customer-facing work that narrative isn't optional. Our take after working through it:
Resulting layered source of truth:
Hardest discipline is updating the index on every PR. We added it as a PR template checklist; if it drifts we'll add CI enforcement. Curious if anyone has tried per-domain organization at scale, or run into limits past ~50 features. |
|
IMO, the code should be the docs as much as possible. I made /grill-with-docs to provide the thin layer of docs that code cannot provide - definitions for jargon and confusing architectural decisions. |
|
I agree with Matt here. I'd like to elaborate slightly from my own experience (pre-AI). Your code should be the document. This does not mean comments in code, it should mean the code, as you read it, makes sense, it "self-comments" because it's not a spaghetti ball of mess. Patterns exist for a reason, not to make people's lives more difficult, in fact the opposite. Same with tests. 99% of the time, I can look at the test, and know exactly what the code should be doing. What helps is structure (both folder and file), variable name choice and consistency across all domains. Especially if you can work in some architecture tests to enforce this across a team. It's truly lovely when you get to that point as you think less about the code, and more about the problem you want to solve. This all explains the "How", and a lot of times you can glean the "Why" from it as well. What you don't always get (almost never, unless the original guy who wrote it still works there), is the context around the problem it solves and the reason why a particular decision / direction was made. This is when it comes to architecture design records and design principle documentation. The ADR describe the key assumptions and decisions made behind some of the bigger decisions made. This usually starts with a Context and Problem Statement, Decision Drivers, Considered Options, Decision Outcomes (with justification) and optionally Consequences of the decision after implementation, Pro's and Con's of the options and Validation. The design principle documentation describes the "how". For example, if you have eventing in your codebase, the document describes how your system should implement. It starts out with calling out your overall principle, for example, "We want the flexibility to make changes to key use cases in the product, without changing multiple subdomains at the same time." and goes in to discuss how it works in your system with example code snippets and any other context that might be required to understand your particular implementation of that. When you need to explain decisions / code, that goes with your code in your repository. Any new programmer picking up your code, will immediately know, How, How to AND why. The above drives outcome based product decisions. When a particular decision was made (Consequences) and it didn't work, document, and update the ADR with what decision was made after as the code evolves, it's usually time stamped and has Author / Change details inside. Similar to when a design principle changes or evolves. Now, you're already asleep reading this, and I apologise, I wanted to be detailed on this; The above is NOT documentation for your user or support staff to use when giving help. The above documentation is for the boys and girls working in the code on the daily. Onboarding new programmers, maybe even a consultant helping out in the codebase. This does NOT document a "Help Centre article". Help Centre articles live on a site somewhere, disjointed from the coding reality. It tells a user about a feature and how to use it, that's it. When a feature evolves, so does that documentation, but it doesn't live next to your code. Above made my transition to AI quite smooth, and I've worked for a lot of companies where "dev docs" weren't a thing, or never updated, and the "why" driver for decisions made in code was lost as people moved on, and you're easily convinced to "not touch what works" or adopt the "it's always been this way", in an attempt to not ruffle feathers. A PRD rarely changes ADR's in my opinion, but it does change design principles on occasion, more often than I've seen ADR's change. But where it should live? Not in an issue on GitHub. That's for sure. "business context, implementation path, data flow, alternatives" -> ADR + design principle documents Would the AI (or any other team member) need that context in an issue? Yes, does the issue link to those documents, YES. An issue should only describe what should change, why it's changing, and what the expected outcome would be. A.K.A, our old friend "User story" *quick edit: Business would use the PRD as the base describing the feature to the users, usually you work with your marketing and customer support team after QA, and an internal release, to get the final version of what the feature is/does, what problem it solves, and how to use it. |
|
Late to this, but the gap named here is exactly what I kept hitting: the workflow flows forward (grill-me → to-prd → to-issues → implement) and nothing owns the PRD's death. I ended up building a small tool for it: you declare the lifecycle in a manifest ( In case it's useful: https://github.com/RubenGlez/doctier |
Uh oh!
There was an error while loading. Please reload this page.
The current workflow is clearly designed to flow forward: `grill-me → to-prd → to-issues → implement`. But what happens to the PRD after the work is done?
Specifically:
Context: The alternative patterns I've seen discussed elsewhere (Spec-Anchored from Thoughtworks/Martin Fowler) suggest keeping the spec as a living governance artifact — but that seems to be a different philosophy from what the skills workflow is designed for. Matt's workflow appears to treat PRDs as one-time planning checkpoints, with the next cycle starting fresh via `/grill-me` rather than updating the original PRD.
The specific gap: If all issues under a PRD are closed, the issue tracker shows progress but the PRD is now potentially stale. There's no skill for "sync PRD with reality after implementation." Is this intentional? What do you recommend for teams that want a persistent source of truth for product documentation?
Curious what Matt's intended answer is, and whether others have developed conventions around this.
All reactions