I define maintainability as the ease with which the intended maintainers can modify a system. In other words, I measure how fast and safely maintainers can add, change, or fix features. Therefore, I treat maintainability as a measurable quality requirement. Moreover, I separate it from acceptance criteria. For example, maintainability is the quality concern. Accordingly, acceptance criteria tell me when the maintainability requirement is met.
First, I identify the intended maintainers. Then, I agree on their skills and tools. Consequently, I can set realistic targets. For instance, I may specify the time allowed to make changes. In addition, I may quantify portability effort. Furthermore, I may define the maximum number of modules to touch for a small change. Specifically, I can state: “A minor bug fix shall take no more than eight hours of a trained maintainer,” or “Porting a feature to a supported platform shall not exceed 40 person-hours.”
I record maintainability requirements early in the RE work products. Therefore, I prevent last-minute reshuffling. Moreover, I reduce redundancy. In addition, I ensure the right notation and level of detail. For example, I choose natural-language-based work products when I need expressiveness. Alternatively, I choose model-based work products when I need precise structure. As a result, I improve the clarity and future maintainability of the requirements.
I define acceptance criteria for each maintainability requirement. Thus, I enable objective verification. For example, I may use these metrics:
- Time to implement a specified change.
- Percent of changes that require only code edits versus documentation edits.
- Number of modules touched per change.
- Time to port code to a target platform.
- Mean time to repair (MTTR) for defects.
Furthermore, I include non-code items. For instance, I specify documentation quality, test coverage, and build reproducibility. Consequently, I make maintenance work predictable. Moreover, I ask: who will maintain the documentation? Then, I assign responsibility. Likewise, I state the required toolchain and versioning practices.
I use clear, consistent terminology. Therefore, I avoid confusion across work products. In addition, I define abstraction levels and how detailed each level must be. For example, at a high level I state maintainability goals. Then, at a lower level I list measurable acceptance criteria. Thus, I keep traceability from goals to tests.
I balance costs and benefits. Although high maintainability reduces long-term cost, it can increase upfront effort. Therefore, I prioritize maintainability requirements with stakeholders. For example, I prioritize maintainability for core modules. Meanwhile, I accept lower targets for less critical components.
Finally, I validate maintainability targets with a pilot or prototype. Then, I refine the acceptance criteria. Consequently, I avoid unrealistic goals. In summary, I treat maintainability as a quality requirement that I define, measure, record, and verify. Thus, I help teams deliver systems that maintainers can change fast, safely, and with clear effort estimates.