What are the best practices for documenting software design assumptions?

There may be a (sub)set of assumptions with ephemeral validity e.g. for the MVP, we want to assume that all our users will be on iOS. Acknowledging the ephemeral nature of such assumptions helps setup boundaries and limit the scope of the MVP and reduce time to market. The school of thought one may often face is the rather unrealistic "Everything is part of the MVP". Use assumptions as a tool to keep the MVP as "minimum" as possible.

NFR documentation is important. If we do a document search in millions of documents vs trillions of documents, design would be different. When a system designed for millions of documents can't handle trillions, a system designed for trillions of documents if used for millions will be costly, take longer time to develop and are more error prone.

We're all on that same quest; to slay the MVP dragon... I'm lovin' the new terms; we might have called this a 'Phase I' back in The Old Days! I'm reminded of that old adage: All projects expand to fit available time/budget. Keep reminding project sponsors that any departure from 'M' means: $$. Speak this language.

An effective way to identified relevant assumptions for your design is thru a benchmarking analysis, this not only work provide you a market tendency it will also provide you a big picture of your competitors and how and what can you do best to exceed.

Divide fundamentals into each word. Fundamental: primary rule Assumptions: Thing accepted as true Divide the assumptions into 3 categories: Persona Assumptions, Business Assumptions, Product-Based Assumptions. There’s no doubt that running through the fundamental assumption activities does require an additional up-front investment of time, energy, and knowledge. Investing the up-front time to research, develop, and validate fundamental assumptions will not only save you time later in the process it will also give you the thorough, clear understanding of your business, audience, and task to develop all of the other parts of your design and marketing strategy. Once starts working, return back to validated ideas to ensure the core values.

When it comes to documenting software design assumptions, it is imperative to adopt best practices that ensure clarity, consistency, and effective communication. In the realm of larger applications and agile development environments, overlooking or mismanaging assumptions can lead to confusion, errors, and project setbacks. Therefore, it is essential to record and communicate assumptions methodically and comprehensively. Assumptions should be documented explicitly and in a standardized format. This documentation should include details such as what the assumption is, why it is being made, and how it impacts the project. Use clear and concise language to ensure that anyone reviewing the documentation can easily comprehend the assumption.

In some scenarios, these links are complex and cannot be defined in single diagram. Breakdown the design artifact if possible or use multiple diagrams to show impact from different assumptions

The period of review should be defined clearly if the teams adopt time based software methodology such as Scrum. I tend to prefer review if there are changes in internal or external factors. Internal changes such as reorganizations, changes in business needs, investment in new technologies, etc. External factors may includes changes in market, external dependencies changes (system that tightly coupled with others), regulations changes (e.g GDPR), etc.