3 ms·
I believe that an optimal architectural document should cover both "why" and "how". Having said that, back when I was writing and modifying such documents at a
by ablekh 6y ago
I believe that an optimal architectural document should cover both "why" and "how". Having said that, back when I was writing and modifying such documents at a CMM Level 3 division of a large and well-known tech company (using the waterfall SDLC process!), relevant information was split between high-level and low-level design documents. I found it quite inconvenient and think that having relevant sections (with cross-referenced info) within the same document makes so much more sense.
- gregmac 6y agoYou need enough "why" so someone reading it doesn't ask, but not so much you're writing a history textbook. Mostly, think about what someone reading this in 6-24 months will think. Without some background reasoning, parts may seem over-engineered and unnecessarily complex. Say the same time, no one will care about the hours of debate that went on, or the shortcomings of the v1 prototype this replaced.
- ablekh 6y agoI agree with you that information (IMO both coverage and level of detail) should be balanced, for the target audience. However, I think that it does not apply to "why" information exclusively. Rather, this is pretty much a universal approach / best practice and, thus, should be applied across all categories of content.