Bootstraping the design model

Good start can make the difference, even when designing software systems. It is quite common to get focused to one aspect of the problem, typically the one that you find especially interesting, and unintentionally ignore other aspects of the problem. Instead of rushing straight into technical topics, start your design activity by modelling the problem itself. This will help to make the resulting software more sound, better prepared for eventual change requests, and will help you to understand what aspects needs to be addressed in the resulting design. The model of the problem also helps to communicate the whole design with non-technical stakeholders or even to get them actively involved into the design process itself.

Start problem analysis with a brainstorming session as a preparation step. The goal of this step is to collect unstructured information that you and other participants know about the problem. Try to answer generic questions, such as what we talked about, who mentioned what, what we can achieve with, what does not work, what has to be considered, etc. You can use a simple plain text format or mind-maps to collect this information. There is no need to be precise or to spent time on discussing if recorded statements are valid. The result of brainstorming session is not a part of the final documentation, but is rather used to recall all aspects of the problem later, when you will be deciding what next steps to take, or to decide if you covered all your initial ideas. 

After brainstorming session, continue with creation of  a problem's description model. The purpose of the problem description model is to establish an ontology for  the software design and to identify problem domain entities that influences the design. The domain entities are either tangible things or abstract ideas, by which users of the system describes their problem. Create links between related entities and decorate them with descriptions expressing the kind of relation and its direction. The examples of the relations are "is kind of", "contains", "influences",  but it can be any other statement, reflecting the actual relation as described by user. Group the entities into semantically similar blocks to depict either sub-domain of the problem or to separate some specific category of entities within the problem description. These blocks and groups are used when deciding about structuring of the system.

The modelling tools usually do not provide dedicated diagram types for problem modelling. The easiest to adapt for that purpose are object diagrams. The resulting model should allow user to discuss the model in his convenient language. Take care you cover the complete problem that need to be solved. Include also entities that either influences the problem, or which can be considered as part of the problem in the future, but explicitly mark such additional entities as "out of the scope" to avoid misunderstandings about the scope of the problem you are going to address. Review collected brainstorming ideas and existing communication materials to check if you covered all necessary aspects of the problem.  

The domain entities depicted in the problem description model are used to pick or to name the important objects in the run-time model of the software system. The close connection between the real problem entities and their corresponding run-time software entities in the resulting system provides a sort of future-proof properties for the resulting design. Future change requests are naturally bound or close to the original problem. They can be easier handled in the system where the designed run-time instances and problem domain entities represent the same things. Opposite to that, it is hard to map a change request to the parts of the system that is structured into pseudo-technical entities without connection to the actual problem. Objects that have no real counterparts tends to evolve into god-classes or into unstructured collections of methods and properties.

Next, collect and define important use-cases for the system. Collect the use-cases from the requirement specification if it already exists, discuss with user and other stakeholders about use-cases they expect from the system, and once again look into notes of the brainstorming session. For each use-case define pre-conditions as the state that the system is expected to hold before the use-case can be activated, define the trigger of the use-case as an action of the actor that invokes the use-case, and define the post-conditions as a state that the system reaches after the use-case is realized. Start with the primary use-cases the user is interested in and with use-cases derived from your business drivers. Less important or auxiliary use-cases shall not break the design that is already addressing the primary use-cases and can be added in iterative way to the existing design.

The use-cases related to the non-functional requirements require special handling. Define expected behavior of the system for each important non-functional requirement, and define negative scenarios for the cases when the requested quality cannot be reached. As an example, let assume you have got a requirement on the responsiveness of the user interface under 200 milliseconds. The negative scenario then defines what is the reaction of the system if the given operation nevertheless needs more time for processing than the specified 200 milliseconds. The behavior can be case specific, e.g. forwarding the processing to the back-end, or showing a progress indicator, but needs to be explicitly defined and consulted with users or stakeholders' representatives. 

Once you feel satisfied with the problem description, review all what you have created, and proceed with the technical design of the system. The information collected so far is the driver of the decisions you will make during the design process. Consider the problem description model as open, and update it when needed. Reflect the actual entities and descriptions of the problem in the names of objects, methods, and classes of the designed software. This, if done correctly, allows for later additions and change requests to the problem definition with only limited impact on the already existing design or implementation.

Is the time spent for such upfront design worth of the effort? I believe there is a kind of upfront design for all code you are writing. That could be a "micro-design" of your imagination of what to do, a "mini-design" you sketched on a paper or whiteboard with a colleague, or a well structured design that is provided to share common vision of the final state between team members and other stakeholders. Writing a code unintentionally, without any design or vision, or without even subtle understanding of the problem is rather improbable. Creating a design in a systemic way is especially important if you want share your efforts with a team, or in cases where you need to convince stakeholders to invest into your vision. In such cases, modelling the problem is worth of the effort and can reduce misunderstandings about what to do and decrease the risk of a failing project.