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.
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.
For me, I can hop ship, decide I don't like it, boomerang back or take some time off no worse for the wear. That level of autonomy doesn't exist when you've got 60 days to land a job or uproot the life you've been building. Salary is a minor part of the picture. If changing jobs is a gamble that might end in "leave the country," the employer gets a certain kind of "loyalty" that salary cannot buy.
I know these abuses happen, no system is perfect. But I feel the bias in the US against H-1Bs from random citizens not from employers. And the government today has quite strong bias against immigrants.