> Do you happen to know of a properly written (publicly available) spec? I'd love to see a good example.
As somebody that has written hundreds of specs and PRDs over the years, I think one of the counter-intuitive things about doing it well is that there is no such thing as a "properly written spec". Or more accurately, "properly written" isn't a single path. You can't really templatize this in a generic way.
Instead, I'd offer the following basic advice which will help to build good specs:
1. Create an outline first, enumerate the list of stakeholders and the sections/topics that those stakeholders are most interested in addressing. Use this outline as the basis for filling in the details.
2. Don't write more than you have to. Rather than being overly verbose, establish the context of what/why/when at the top of the document in a summary, and then focus only on the most relevant conclusory details in each section after. The more shared domain knowledge the stakeholders have, the less you have to write.
3. A good spec results in a finished product/feature/widget. Be clear about what you know, what you don't know, and what you believe. Leave room for things to be discovered during implementation. Be concise.
Basically, don't write more than is necessary to actually achieve what the output of the spec is trying to achieve given the team/organizational context that the spec is going to be used in. Be as concise as possible, eschewing verbosity when possible because shared knowledge already exists. For this reason, "properly written specs" are very team/organization/project/product/person dependent. There's no universal format that works.
As somebody that has written hundreds of specs and PRDs over the years, I think one of the counter-intuitive things about doing it well is that there is no such thing as a "properly written spec". Or more accurately, "properly written" isn't a single path. You can't really templatize this in a generic way.
Instead, I'd offer the following basic advice which will help to build good specs:
1. Create an outline first, enumerate the list of stakeholders and the sections/topics that those stakeholders are most interested in addressing. Use this outline as the basis for filling in the details.
2. Don't write more than you have to. Rather than being overly verbose, establish the context of what/why/when at the top of the document in a summary, and then focus only on the most relevant conclusory details in each section after. The more shared domain knowledge the stakeholders have, the less you have to write.
3. A good spec results in a finished product/feature/widget. Be clear about what you know, what you don't know, and what you believe. Leave room for things to be discovered during implementation. Be concise.
Basically, don't write more than is necessary to actually achieve what the output of the spec is trying to achieve given the team/organizational context that the spec is going to be used in. Be as concise as possible, eschewing verbosity when possible because shared knowledge already exists. For this reason, "properly written specs" are very team/organization/project/product/person dependent. There's no universal format that works.