In today's software world, there are boundless discussions and thoughts around "how best to develop software." There are many books and standards written on this subject. However, it all comes down to the organization, the expectations of the users/business, and how much time and money is provided to software projects. There are certainly many other factors, but for now, we will focus on these major topics.
|The Integrated Development Environment (IDE) directs an organization toward specific tools as well as techniques of modeling.</ b>|
In an organization that requires the type of documentation described here, there are several possible approaches to design and modeling techniques. Most of the expectations in any development organization are focused on creating the code. While design is an absolute necessity, the method of describing the design varies greatly, as does the techniques used to produce such designs. The level of detail will often dictate the effort and time required to produce the artifacts that communicate the design of the system.
Technology offers some great capabilities in pulling together the design of any software system. Regardless of platforms, the technologies available to create models are vast and highly efficient in today's development world. Design techniques include standard modeling languages such as the Unified Modeling Language (UML), frameworks such as the Model-Driven Architecture (MDA), and software processes such as the Enterprise Unified Process (EUP). Tools are available for download, purchase from various vendors, and even developed in-house. Modeling tools that support the standards should be the first choice for organizations. The Integrated Development Environment (IDE) directs an organization toward specific tools as well as techniques of modeling.
In most discussions of "how" modeling is accomplished, the conversation will ultimately include topics such as diagrams, artifacts, technologies, and platforms. While this certainly does not sum up modeling as a phase of development, it is often the primary considerations. While having these discussions will guide the organization towards appropriate decisions of "how to design," you must also consider standards such as the Software Engineering Body of Knowledge (SWEBOK), IEEE 1074-2006, and ISO 9001 for appropriate design techniques and concerns.
Modeling techniques usually comes down to artifacts (diagrams). You must define the desired artifacts for the system definition, the audience for the artifacts, and how the artifact will be used. If documentation is the goal, then technology and techniques should work toward delivering structured output, be that in the form of a document or a graphics representation of the design (diagrams). The goal should be to produce only what is needed and what is effective to communicate the design. You should not produce content or artifacts "just because you can." Reduce output for the system specification to pertinent details, focusing on the needs of the audience.
If you want to effectively communicate the architect's design to the developers producing the code, then technology that closely ties design techniques with the resulting code should be your focus. Little attention to documentation output and large focus on effective communication will help produce desired project results. People and processes define effectiveness for development results while technology defines the efficiency of that same effort. Design is the software development life cycle (SDLC) step between the customer needs and the developer code. Make that step as streamlined and effective as possible while being efficient on the part of all interested parties. If customers don't need to see it, discuss it, or approve it, then do not consume their time by producing it. If developers spend unnecessary cycles translating documents to code, give them efficiency by sharing design technologies in the coding phase. The techniques that accomplish bringing together requirements, design and code should be the focus for improving the development effort. This is true whether waterfall or agile methods are the software development process for the organization.
What goes in an SRS?
Regarding the Software Requirements Specification (SRS) in consideration of design, we must face the annoying statement of "it depends." Whenever an SDLC calls for a detailed SRS, a definition of what content must be included is required. Thus, the "it depends" begins here. It depends on topics such as agile versus waterfall processes, intended audience, knowledge and skill of reviewers, and time allowed developing content.
Many professionals say the SRS should focus only on the customer's business needs (Business Requirements Document - BRD) and not on implementation (Functional Design Document - FDD). This is the separation of requirements from design. These factors will usually dictate that only the "What" and the "Why" for the customer are included in a BRD. This will focus the document on the business needs, the customer's specific needs, the flow of customer's actions, and possibly the environmental needs. This is where Use Case content along with business details come together to provide a detailed requirements or feature specification such as a BRD.
Going beyond this level of specification begins to focus on implementation. Thus design of the system, the functionality, constraints, integrations, and interfaces are considered beyond a BRD and are truly an FDD. Creation of this level of detail requires a level of technical understanding that is beyond many customers. If the SRS is to bring about an agreement with the customer and development (BRD), design details in the SRS is usually going too far (FDD).
Certainly, the audience plays a big part in the content of an SRS. If the audience is technical in nature such as architects, data modelers, and interface designers, then design with requirements begins to make sense. By including the customer's needs with design details, the technical audience will gain a full understanding of the system being developed. If the audience includes very technical customers, there may be a benefit to including design details in this particular case. But it is indeed a case-by-case basis. This detail specification will be wasted on customers that are not technical. These audience considerations are why many organizations develop business requirements documents and functional design documents separately.
When you take these considerations into an agile environment, many of the same discussions and factors are still expected but may happen at varying times from a traditional waterfall approach. Requirements are still necessary in an agile methodology. The difference is how requirements are elicited, how those requirements are documented, and when these efforts occur in the process. Iterations and content will drive these efforts rather than a full frontal attack on gathering all requirements at the beginning of the discovery process.
This was first published in October 2008