This article first appeared in magazine and is brought to you by InfoQ & IEEE Computer Society.Software architects must create designs that can endure throughout software evolution. Today, software architecture comprises not only a system’s core structure but also essential design decisions. 1,2 So, to achieve sustainable architectures, we need sustainable design decisions. In correspondence with Heiko Koziolek’s definition of architecture sustainability, 3 we argue that architectural design decision sustainability involves. the time period when the right and relevant decisions remain unchanged, and. the cost efficiency of required changes to those decisions. NGINX Plus is the complete application delivery platform for the modern web.Although research has dealt with software architecture sustainability 3 and corresponding evaluation methods, 4 it hasn’t yet revealed how to make architectural design decisions sustainable.

• Software Design Document Template Example

In more than 10 industrial projects and eight research projects, we’ve applied various techniques to yield sustainable architectural design decisions. Here, we describe the fruits of our experiences: the challenges to achieving sustainable decisions, the criteria for such decisions, the solutions we tried, and the lessons we learned. Challenges to Achieving Sustainable DecisionsMany researchers and practitioners consider architectural knowledge (AK) to be an inherent part of software design. They point to the importance of capturing significant architectural design decisions together with other software artifacts because those decisions can ensure that the design rationale doesn’t get lost. 5 Capturing significant decisions and their rationale is difficult and often neglected because doing so requires considerable effort. 6,7 In this context, architects should seek to make and document sustainable decisions. However, various challenges can hinder this desire.

Decision Documentation EffortA key challenge in various industrial cases is that the relatively high effort needed for design decision documentation 6 often isn’t well accepted. Many decision templates require filling in 10 to 20 fields to document a single design decision. Although each documentation attribute is important, this documentation frequently takes too much effort, so architects on high-pressure projects often neglect it. 7 Therefore, software architects and project managers tend to disregard such practices over time, leading to decision rationale erosion in the long term.

Another consequence of strained time for decision documentation is low-quality documentation. For example, if a decision’s rationale is “the end user wants it,” the documentation isn’t likely to be useful over time. Understanding the Links between Decisions and Other Software ArtifactsWhen documenting design decisions, it’s important to establish links to other software artifacts such as requirements and architecture designs.

8 However, although many architectural-decision-capturing templates implicitly mention requirements, establishing and maintaining the right set of traceability links between the decisions and other software artifacts is time-consuming and difficult. But as we’ll see, capturing the right set of links can help increase decisions’ sustainability. 3 Avoiding Repetitive EffortMany decisions are based on existing AK in the project or field. For example, in many service-oriented architecture (SOA) projects, service proxies and adapters must integrate legacy systems, each with only a slightly different design. So, each proxy and adapter requires its own decisions, but many of them are similar. Instead of documenting each decision on its own, we would like to reuse the AK and work only with variations of individual decisions, reducing the documentation effort and allowing decisions to be based more on timeproven knowledge. Dealing with Invalid or Bad RationalesDecision drivers and the pros and cons of alternatives, recommendations, and rationales are particularly relevant when you’re capturing design decisions.

Software Design Document Template Example

However, architects sometimes choose bad or invalid rationales, leading to decisions that can be questioned and hence are unsustainable. Consider this valid justification for the external stakeholders’ needs:Alternative A best meets user expectations and functional requirements as documented in user stories, use cases, and the business process model.Compare it to this poorly chosen justification:End users want it, but no evidence exists of a pressing business need. Decision Sustainability CriteriaTo define decision sustainability in detail, we derived five key criteria. StrategicDuring decision making, someone looking at strategic consequences should consider things such as the decisions’ long-term impact—for example, future operations and maintenance effort. Measurable and ManageableYou can measure and evaluate a decision’s outcome over time according to objective criteria, ideally numeric ones (as, for instance, propagated by quality attribute scenarios and workshops4). Capturing all fine-grained decisions isn’t possible, so architects must limit the decisions’ granularity to a certain level of detail (such as creating a design class).

This will lead to a more sustainable set of decisions and fewer traceability links. Moreover, limiting the number of dependencies between decisions reduces changes’ ripple effect. Achievable and RealisticThe rationale for fitting the solution to the problem should be chosen pragmatically and made explicit. For example, architects can indicate that they have taken care to avoid over- or underengineering (that is, they should apply the “good enough” approach).

Rooted in RequirementsDecision making should be grounded in domain-specific architecting experience and context. It should take into account the company environment as well as project requirements and constraints, including the development team’s current skills, training budget, and process. TimelessDecisions should be based on experience and knowledge that won’t likely be soon outdated. For example, architects can choose platform-neutral architectural patterns or tactics. Criteria DiscussionThese five criteria strongly relate to the decision life cycle because software engineers need to track every change, regardless of whether the decisions are still valid.3 So, the decisions’ evolution across the life cycle clearly affects the degree of sustainability achieved at any time. Moreover, although not all these criteria apply to every decision, our experience shows that sustainable decisions often meet most of these criteria.Solutions and Lessons LearnedTable 1 summarizes the lessons we learned from applying techniques for organizing, documenting, and evolving architectural design decisions. (We will discuss these in more detail later in this article.) Although these results are based on the various industry and research projects in which we’ve been involved, we focus here on one case from the COMPAS project: customer relationship management (CRM) fulfillment.In the case from the COMPAS project, a customer initiates CRM fulfillment by placing an order for an ISP’s services.

The fulfillment process involves initializing the services, shipping the necessary equipment, charging the customer’s account, and sending the customer an invoice. It also incorporates functionality provided by three service-based platforms including CRM, billing, and ISP provisioning systems. The main company’s bundle of Internet and telecom services includes a network subscriber line, email addresses, Webbased administration, directory numbers, fax numbers, and voice-over-IP communication.In the COMPAS project, we were confronted with short development iterations because working prototypes had to be delivered frequently. So, collecting all the requirements and delivering a full architecture design and documentation upfront wasn’t feasible. On the other hand, if important design decisions weren’t sustainable, they could impede continued development and integration.

Central requirements for this project were to capture and document the relevant compliance requirements stemming from the relevant regulations and legislation, as well as the ISP’s business policies, and ensure that the systems complied with them. Initially Apply Lean, Minimalistic Decision DocumentationTo reduce design documentation effort, we experimented with lean, minimalistic documentation. One approach was our (WH)Y approach (named for its Y-shaped visualization), inspired by George Fairbanks’s proposed documentation of design rationale.

The IEEE provides standards for software documentation. For instance, high level requirements are defined in IEEE 830-1993 Software Requirements Specification.This is a standard I've learned in school (using a book called Software Engineering - an object oriented perspective by Eric J. Braude, but I would not specifically recommend it.) It's more suited to a traditional waterfall development model though.Googling the standard number should get you a couple of interesting links.(The IEEE 830-1993 standard is superseded by IEEE 830-1998.).