> Think of a design document like a proof in mathematics. The goal of a proof is to convince the reader that the theorem is true. The goal of a design document is to convince the reader the design is optimal given the situation.
We don't need to veneer technical writing in faux rigour for it to be worthwhile. That's the silly stuff that belongs on LinkedIn.
This kind of psuedo-rigor feels good to nod along to, but it's nonsense.
'We're not writing code, we're programming', 'we're not just programming, we're doing software engineering', and now 'we're not doing software engineering we're doing rigorous proof based mathematics' all of a sudden.
IDK how you write 'Think of a design document like a proof in mathematics.' without feeling at least a little bit silly.
> The goal of a design document is to convince the reader the design is optimal given the situation.
A proposed design may be optimal, or it may not, but the purpose of a design document is not to prove that the proposed design is optimal by any definition.
In a software development setting you're virtually NEVER formally proving anything, nevermind optimality.
You're writing technical fiction based in reality, nothing more. It's not a 'proof' of anything.
You're convincing stakeholders that your proposal can be feasibly built, is viable to run in the ecosystem of the rest of your codebases and infrastructure, and satisfies whatever business requirements that led to someone asking you to create a new $thing the design doc is aiming to propose the technical solution for.
Nothing more IMHO.
If your doc isn't doing those things then it's not effective, if it's giving the illusion of trying to do more than those things then it's just theatre.
The rest of the article is standard good writing advice, but can we not put design docs and PRFAQs on an altar as anything more than technical business fiction to communicate ideas and proposals for scrutiny to stakeholders.
Oh, I interpreted design documents as general things - documentation included.
Plenty of things at my current job have formal mathematical proofs backing it and it's helpful when justification is explained like that.
Invariants in networking architecture i need to carefully manage etc.
Depending on the culture some of this stuff is also needed once you get into politics land and need to present your ideas because you know it's better, no? Ig at a large company with too many business oriented minded people this line of work would fall flat
This is my problem with design documents. If your stakeholders already have enough trust that they ask you to go build it without writing a doc, then what value does writing a design doc have.
Many will answer that it helps them think. But why do we need a formal process to think? Thinking is a valuable skill that should be practiced all the time.
Writing for yourself is a good way to think.
Writing is also s good way to document to others that you have thought about the topic/problem/solution.
I have both read and written several design docs containing informal correctness proofs of nontrivial concurrent/ distributed protocols, so not sure where your dismissive attitude comes from. Not everyone’s environment or experience is exactly like yours.