I'm afraid not. The best I can do right now is offer an example outline of what I do. That said, if I'm working with a good project manager my format will differ: I'll focus a lot more on the technical details and leave all organizational aspects out (e.g. timelines, dependencies and impact on other teams, etc).
The key principle is that anyone (sales, marketing, support, product, etc) should be able to benefit from reading it and find it intuitive to see where you're getting into the technical details and skip ahead to the next major point.
1. Overview
A paragraph of two explaining the what and why of the project. Maybe some links to other related key documentation. Don't put anything technical here.
2. Change Log
Bullet-point list of dates and major changes. Think of it like a git commit history.
3. Scope
What systems are affected? Are there phases to the project to be called out? If its principally one system/repo/etc in question, what major components are changing?
4. Requirements/Tasks (the main body)
Use a numbered list and aggressively refactor as you go so high-level items rise to the "left" and all related details are broken out as sub-lists. You can loosely think of it as something like "[section] > [epic] > [task], [task], [task]". Prioritize the list based on dependencies so you're always referring back to already-mentioned requirements instead of yet-to-be defined things.
5. Supporting Docs
Put long-form examples, scenarios, diagrams, etc in their own section. Some people will only care about these, especially if they provide integration examples.
6. Concerns and Questions
Ideally by the time a first draft is done this section no longer exists, but usually you'll find that you need to do research or get feedback from others to finalize the whole thing.
> 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.
Not sure this is exactly what the commenter had in mind, but I think of Clojure's "design rationale" documents as good examples of thinking through a problem before executing. This is one for the language itself, but there are loads of others out there for other sub-projects.
* ITU Recommendation on H.323 Protocol for Packet Based Multimedia Systems.
* The NIST documentations on FIPS and the various Crypto algorithms.
The first two are an "umbrella" of protocols and thus the specifications go from overview to extremely detailed in a very nice step-by-step manner. The third one shows you how to specify detailed and complicated algorithms.
Writing good Specifications is extremely demanding! But this is the only way to really understand the Domain.
"What even is a good specification, or the Huaqiangbei test"
Those three points are pure gold!
I'd also add that you don't need to be working on a major project to benefit from standing back to writing it out first. Much of what I write is just a few pages, but it's still useful. It saves time overall, helps others get up-to-speed fast, and is fun!
The key principle is that anyone (sales, marketing, support, product, etc) should be able to benefit from reading it and find it intuitive to see where you're getting into the technical details and skip ahead to the next major point.
1. Overview
A paragraph of two explaining the what and why of the project. Maybe some links to other related key documentation. Don't put anything technical here.
2. Change Log
Bullet-point list of dates and major changes. Think of it like a git commit history.
3. Scope
What systems are affected? Are there phases to the project to be called out? If its principally one system/repo/etc in question, what major components are changing?
4. Requirements/Tasks (the main body)
Use a numbered list and aggressively refactor as you go so high-level items rise to the "left" and all related details are broken out as sub-lists. You can loosely think of it as something like "[section] > [epic] > [task], [task], [task]". Prioritize the list based on dependencies so you're always referring back to already-mentioned requirements instead of yet-to-be defined things.
5. Supporting Docs
Put long-form examples, scenarios, diagrams, etc in their own section. Some people will only care about these, especially if they provide integration examples.
6. Concerns and Questions
Ideally by the time a first draft is done this section no longer exists, but usually you'll find that you need to do research or get feedback from others to finalize the whole thing.