1. Background

In the software development industry we often come across a challenge in designing the program based on the requirements. If we have a design that is detailed and lays out what needs to be done then writing code would be merely an exercise of placing the correct syntax for the chosen computer language. However, such detailed design is generally considered as impractical as a software development project has a set budget and delivery date. A higher level of design is more cost effective but it requires a certain set of design elements to be covered before it can be of any use. In the following section the different design elements are discussed.

A document that shows the software design is created for that purpose. This type of document is commonly known as SDD or Software Design Document.

2. The 3 elements in Design

When we are doing the design we need to transform the solution of a problem belonging to the business domain into a solution in the technical domain. The difference there is that, business domain would often need to solve problems that are pliable in nature, whereas, the technical domain deals with matters that are concrete and definitive. So when we reach a solution to the business problem, it is often the case that technical domain does not map to the solution in a one-to-one fashion. We often have to do a lot of work get the business solution implemented in the technical domain. If we could map the solution from business space to the technical space then we could get a quantifiable measure of the technical work that is necessary. Such mapping could be done by describing what the system could do and which portion of the system does what. What the system could do could be described by user stories. To describe which portion of the system encapsulates what functionality, functional components can be used. Thus, in design we can have the following 3 elements.

• User Story creation.
• Functional breakdown into functional components.
• Technical component design and distribution across functional components.

2.1. User Story:

It explains the system from the point of view of a user and details the activities/functionalities that the user can perform.

A <user of certain user group>, can perform <some action> so that <some end result is produced>.

The entire collection of user stories should describe what the whole system could perform.

2.2. Functional Breakdown:

It explains the system from a functional component point of view and maps all the requirements into different functional components.

Generally the breakdown begins with large components with broader scope and then they are broken down further into components with more specific set of responsibilities. This establishes the relationships between different functional components.

The entire collection of functional components should describe what the system is made of from a functional point of view.

2.3. Technical Components:

This design step explains the design of the technical components within the scope of each functional component. Some technical components could be shared by different functional components. Certain core functionalities could be encapsulated in their own functional component. A map of technical to functional components could be produced as a design artifact. The functional components could act as the starting point to identify the domain objects, service classes etc. in an object oriented design.

The user stories will be explained using the technical components. UML diagrams such as sequence diagrams or activity diagrams could be used to explain this further.

The entire collection of technical components should allow the user to perform the actions outlined in the requirements in the manner outlined in the user stories.

3. SDD vs. TRD

The document that captures the design element is commonly referred to as Software Design Document (SDD). The design document is often confused with Technical Requirements Document (TRD) as this style of documentation also provides insight about the system from a technical point of view. To make matters even more confusing, both SDDs and TRDs use the Functional Requirements Document (FRD) as the input. However there is a fundamental difference between SDD and TRD. An SDD will try to explain what the actual elements of the design are. A TRD on the other hand, is still a requirements document but at the level of detail where the information includes technically what is required. An SDD will show the pieces and will also show how the pieces fit. The target of the TRD is to show only the pieces. Consider the example of a box of Lego blocks. The information on the box itself about how many types of different pieces it has can be considered as the TRD. The manual inside the box of how to build the model is analogous to an SDD. The demand of your kid for a fire truck with a ladder and yellow lights can be considered as the FRD.

However, in practices, TRDs often include design specifications (how pieces fit together). At that point it turns into an SDD though it may still be called a TRD.

4. At what point SDD is created in SDLC

Ideally before we can begin to do any development work we should have the design ready. If the project is following the waterfall methodology then this could be accomplished right after the requirement analysis. If however, it’s agile or some form of iterative approach, then we need to have an overall design, which should be a high level design. As we progress through each sprint we need to have the detailed design for the items covered in a particular sprint.

For both the methodologies: waterfall and agile, the effort required for capturing the design decisions in the form of a software design document requires a certain amount of effort. It could be argued that since the methodologies are fundamentally different the design document should be of a different format. In my opinion though, this need not to be the case. If we can express our design in terms of functionality, user-interaction and the technical pieces then in both Agile and Waterfall we can have the same structure for a design document.

5. Structure of the SDD

A good SDD needs to express the design from 3 angles:

• User interaction with the system (user stories).
• Functional point of view (Functional Components).
• Technical components.

The SDD should begin with the overview of the functional components and the technical components. Within the technical component the entities that have been identified could be described. The database schema, configuration entries, server side classes etc. could all be a part of the technical components section.

The user stories section should describe the entire collection of the user stories. Then for each user story it should show a set of sequence diagram detailing different technical components and how they get invoked.

Then for each functional component, further details can be provided including sub components with user stories complementing the overall user stories.

A sample of the document structure is given below:

6. Conclusion

A good design done early in the project can result into good estimates of the effort required. Also during the life of the project it would give a clear picture to the project manager about the progress of the project. Statement of Work can be prepared based off of the delivery of the functional components.

Following the above methodology it ensures that all the functionalities of a system gets captured in a manner that is understood by the developers and the business analysts alike resulting in a clearer communication of the expected end result of a system.

When it comes to maintainability, such SDD could prove immensely valuable as the support team could easily navigate to a problem zone and identify what would be the side effects of a possible solution.

Therefore, the above design method has the potential to cut down cost during development and in the future support period.