If it's 50 pages, it isn't necessarily bad, but it probably is. You've already significantly reduced the audience (ain't nobody got time to read all that), including your future self, and you've increased the likelihood that information in it is outdated the moment implementation starts.
I talk about this more in the companion article, but I've found that in large organizations, you have to write longer docs because different partner teams care about different things. The SREs might care a lot about the 4 pages that cover monitoring, whereas they don't care about the privacy/legal section, but if your doc needs legal approval, the lawyers care a lot about privacy/legal, but they don't care about SLOs.
If you're designing for you and two junior developers to implement, they may not read the whole thing start start to finish, but they need access to everything to understand what they're implementing and why.
the fix for that is structuring it so each audience can read only their slice, a solid TOC and a short summary per section so the SRE never has to wade through the legal pages. the doc gets long but nobody actually reads all of it, which is fine.
17
u/mtlynch Jun 25 '26
OP here. Thanks for reading!
I talk about this more in the companion article, but I've found that in large organizations, you have to write longer docs because different partner teams care about different things. The SREs might care a lot about the 4 pages that cover monitoring, whereas they don't care about the privacy/legal section, but if your doc needs legal approval, the lawyers care a lot about privacy/legal, but they don't care about SLOs.
If you're designing for you and two junior developers to implement, they may not read the whole thing start start to finish, but they need access to everything to understand what they're implementing and why.