arc42 section 1: Introduction and Goals

Requirements overview, top quality goals, stakeholders

• The document lists the three most important stakeholder quality goals. → Architecture Canvas
• The documentation records which stakeholders were asked what information they expect. → Characteristics of a Good View
• Documentation sources are plain-text markup (for example AsciiDoc or Markdown) kept in a version control system such as Git. → Documentation as Code
• Each section of the document was included because a named stakeholder needs it, not just because the template has it. → Guidelines for Documentation
• The architecture description consists of at least one architecture view. → ISO/IEC/IEEE 42010 Architecture Description Model
• The document describes the architecture through one or more architecture views. → ISO/IEC/IEEE 42010 Architecture Description Standard
• The description is kept distinct from the architecture of the system it describes. → ISO/IEC/IEEE 42010 Architecture Description Standard
• The document records the reasons behind important decisions, not only the decisions themselves. → Motivation for Architecture Documentation
• The content is limited to what stakeholders need, so people can find and update it. → Motivation for Architecture Documentation
• The document contains a stakeholder overview that lists roles and each stakeholder’s expectations of the architecture and its documentation. → Stakeholder Perspective and Concern
• Each viewpoint names the stakeholders whose concerns it reflects. → Stakeholder Perspective and Concern
• The documentation lists its stakeholders, including those who need it for their work. → Stakeholder Questions Addressed in Views
• The architecture documentation is organized by the twelve arc42 sections, tailored to the project’s needs. → arc42 Architecture Documentation Template
• Section 1 lists at most five quality goals. → arc42 Introduction and Goals
• Each quality goal has a brief scenario, not just a keyword. → arc42 Introduction and Goals
• The stakeholder table gives roles, names and expectations. → arc42 Introduction and Goals
• Chapter 10 references the top quality goals from section 1.2 and adds further, lower-priority requirements. → arc42 Quality Requirements
• The most important quality requirements are only referenced in chapter 10, because they are described in section 1.2. → arc42 Quality Requirements Chapter
• Stories that feed the documentation are labeled with the domain experts’ own terms. → Domain Storytelling
• Each planned landscape change is tied to a documented business goal or driver. → Application Landscape Evolution Drivers
• Business capabilities are described as what the business can achieve, without people, processes, data or technology. → Business Architecture
• Capabilities are described without people, process, data or technology, and are kept separate from processes. → Business Architecture Artifact
• Heat maps color capabilities by a stated criterion such as maturity. → Business Architecture Artifact
• Capabilities are described as what the organization can do, not as steps of how work is done. → Business Capability
• Each capability states what the business must be able to do, not how it is done or who does it. → Business Capability Map
• Capabilities describe what the business does, not processes, workflows or systems. → Capability Map Development Method
• The capability map is decomposed below level 1 so it is usable for decisions. → Capability Map Use Cases
• Applications are mapped to capabilities to find redundancies. → Capability Map Use Cases
• Capabilities are named with nouns or gerunds, and processes use verb-noun names such as Receive Order. → Capability versus process
• The architecture document references an approved Statement of Architecture Work that sets the scope of the data architecture effort. → Data Architecture Inputs
• The document states which operating model (diversification, coordination, replication or unification) the company follows. → Enterprise Architecture (Ross/Weill/Robertson definition)
• The document states the target maturity level and explains why it fits the organization’s size and complexity. → Enterprise Architecture Maturity Level
• The current maturity is assessed and a roadmap of EA initiatives leads toward the target. → Enterprise Architecture Maturity Level
• The document states which maturity stage the firm is in today and which model version (four or five stages) it uses. → Enterprise Architecture Maturity Stages
• The document explains how architecture influences investment decisions. → Enterprise Architecture Maturity Stages
• The document explains how change is measured and how its value is communicated to stakeholders. → Enterprise Architecture Strategy
• The document names the operating model, the enterprise architecture and the IT engagement model as the basis for execution. → Foundation for Execution
• The document states how much process standardization and integration the business needs. → Operating Model
• The operating model is kept separate from the business model and describes only how value is delivered. → Operating Model
• Each operational value stream names the stakeholder who triggers it and the point where that stakeholder’s need is satisfied. → Operational Value Stream
• Each critical stakeholder has a current and a required commitment level, so the gap is visible. → Stakeholder Readiness for Change Assessment
• The stakeholder table uses H/M/L ratings and includes ability to disrupt, understanding, commitment and required support. → Stakeholder Readiness for Change Assessment
• The analysis was done in Phase A and is kept up to date in later phases. → Stakeholder Readiness for Change Assessment
• Cause-and-effect arrows run bottom to top, and each link is treated as a hypothesis to test. → Strategy Map
• The map has roughly 12–20 concise, action-oriented objectives across its perspectives. → Strategy Map
• The document or an inventory lists existing business capabilities, so teams can find and reuse them instead of rebuilding. → Warning Signs of Poor Enterprise Architecture
• Known workarounds (kludges) are recorded as risks rather than left implicit. → Warning Signs of Poor Enterprise Architecture
• The document states which framework cells are formalized and which are deliberately left out, with the risk accepted. → Zachman Framework
• The framework is used as a classification structure, and the order of work and tools are defined separately. → Zachman Framework
• The document names the business drivers and prioritized quality requirements that the chosen architecture style is meant to serve. → Fitness for Purpose
• The document lists a small set of significant quality scenarios, roughly ten. → Architecturally Significant Requirement
• Stakeholder concerns are explicitly addressed in the architecture description. → Concern
• The people involved in a decision are grouped in a RACI matrix. → RACI Matrix
• Stakeholders and their expectations are recorded, for example in a table with roles and expectations. → Stakeholder Concern
• Each viewpoint names the stakeholders and concerns it reflects. → Stakeholder Concern
• The document shows that requirements and architecture were refined together, in mutual interplay. → Twin Peaks Model
• Each user story lists its own acceptance criteria, separate from the team-wide Definition of Done. → Acceptance Criterion
• Criteria can be turned into detailed test cases. → Acceptance Criterion
• Stories are marked done only when an acceptance test passes. → Agile Enterprise Backlog Model
• System validation tests exist to verify the nonfunctional requirements. → Agile Enterprise Backlog Model
• Each story has a brief card or name, and the details are not stuffed into it. → Card, Conversation, Confirmation
• Each story has confirmation (acceptance criteria, examples or tests) that tells the team when it is complete. → Card, Conversation, Confirmation
• Agreements on a story are documented as confirmation tests, not only on the card. → Card, Conversation, Confirmation
• Stories too large for one iteration are labeled as epics and not scheduled for implementation as they are. → Epic
• Epics that are not yet needed stay as placeholders without detailed specification. → Epic
• Acceptance criteria are written in the user’s behavior and language, not as implementation steps. → Frequent Mistakes in Defining Acceptance Criteria
• The user’s goal stays visible next to the criteria. → Frequent Mistakes in Defining Acceptance Criteria
• Stories are written so they can be scheduled and built in any order, or the dependency and its effect on estimates is stated. → INVEST Criteria
• Each story states value to the customer, not only technical work. → INVEST Criteria
• Each story has an estimate good enough for the customer to rank and schedule it. → INVEST Criteria
• Business requirements are recorded in a vision and scope document, separate from detailed software requirements. → Requirement Types and Documents (Wiegers/Beatty)
• The document names how and how often the team gets feedback from customers or users, such as sprint reviews or an on-site customer. → Requirements Difficulty and Customer Engagement
• The document states who invites stakeholders to reviews and who receives priority change requests. → Requirements Difficulty and Customer Engagement
• The document shows that requirements were gathered with more than one technique, such as interviews, observation, questionnaires or workshops. → Requirements Trawling
• The document accepts that requirements are incomplete and will change, and does not claim a complete specification. → Requirements Trawling
• Each requirement is worded without ambiguity, with consistent terminology and an appropriate level of detail. → SMART Requirements
• Each requirement has been judged technically feasible, and also realistic given staff, skills, infrastructure and time. → SMART Requirements
• The map’s cards are short verb phrases, each describing one user step. → Story Mapping
• Releases are marked as horizontal slices, starting from one objective or MVP. → Story Mapping
• Large stories were checked against INVEST (ignoring size), split with named patterns, and the split was then evaluated. → Story Splitting
• The first story delivers a simple end-to-end case before variations in data or interface are added. → Story Splitting
• Each use case is marked with its goal level. → Use Case Completeness Check
• The use case set was checked against non-functional requirements and domain concepts, not only by asking stakeholders. → Use Case Completeness Check
• Each use case is labeled with its goal level, so readers know what kind of discussion to expect. → Use Case Goal Level
• Subfunction use cases exist only where several user-goal use cases reuse them. → Use Case Goal Level
• Each use case names a primary actor, a trigger and the preconditions that must hold before it starts. → Use Case Template
• Extensions cover error handling and special cases, each as a condition that leads to different interactions. → Use Case Template
• Each user story is backed by acceptance tests or examples that confirm it. → User Stories vs. Use Cases
• Requirements chosen for estimation and prioritization are small enough to estimate usefully. → User Stories vs. Use Cases
• Each story names a type of user, a goal and a reason or benefit. → User Story
• Each story has customer-defined acceptance tests that show it was implemented correctly. → User Story
• Stories name a specific user role instead of starting generically with ‘As a user’. → User Story Role Formulation
• Each story states a reason or benefit, or the team has chosen on purpose to omit it. → User Story Role Formulation
• Each story has acceptance criteria that show how the team will know it is complete. → User Story Role Formulation
• The document briefly describes the functional requirements and refers to existing requirements documents. → Working with Functional Requirements (method phase)
• The context view shows the system as a black box with its communication partners and the data exchanged. → Architect’s Four Key Work Products
• Assumptions about scope and security needs, such as ‘only a simple login’, are written down and have been challenged. → Common Architect Mistakes
• The document names the quality goals of the most important stakeholders. → Requirements and Means Influence Architecture
• Architectural decisions are documented together with their justification. → Role of the Software Architect
• The document names who acts as architect and who is responsible for meeting requirements and the architecture design. → Software Architect
• The document states the rationale behind the architecture, not only its structure. → Software Architecture
• The document states the requirements and driving forces the architecture must consider. → Software Architecture Basic Concepts
• The document states which definition of architecture the team uses, such as design decisions about overall structure and behavior. → Software Architecture Definition
• The document makes clear which parts of the system the team treats as important. → Software Architecture Definition
• Constraints that limit design and implementation freedom are listed, grouped as technical, organizational, political or conventions. → Software Architecture in Its Context
• The document shows which constraints are fixed and which may be negotiable. → Software Architecture in Its Context
• Every actor is a person, organization or external system that interacts with the system. → Use Case Diagram
• Each principle has a Name, a Statement, a Rationale and Implications. → Architecture Principle Structure
• The documented requirements come from the target-state process, not only from the current-state process. → Process Automation Magnifies Efficiency
• An interaction identifier links the events of one user interaction across components. → Accountability
• The document states whether adaptability covers changed requirements, or only a move to another platform. → Adaptability
• The document uses the current ISO 25010 names, with adaptability listed under Flexibility. → Adaptability
• The availability target is stated as a percentage over a defined period, such as a month or year. → Availability
• Data is classified by type, sensitivity and risk, and each class has an assigned confidentiality level. → Confidentiality
• The document states which Flexibility sub-characteristics (adaptability, scalability, installability, replaceability) matter for the system. → Flexibility
• The document states which tasks and user objectives the functions must cover (functional completeness). → Functional suitability
• Functional suitability is treated as one product quality characteristic next to others such as security. → Functional suitability
• Availability requirements say the system must be operational and accessible when required for use. → ISO/IEC 25010 Product Quality Model
• The document states which target (ICT product, data, or IT service) each quality model is applied to. → ISO/IEC 25010 Quality Models and Their Target Entities
• Requirements that once referred to maturity or UI aesthetics now refer to faultlessness or user engagement. → ISO/IEC 25010:2023 Product Quality Model Revision
• Installability is placed under Flexibility, with the model version stated, and is kept distinct from adaptability, scalability and replaceability. → Installability
• Quality goals are stated concretely, without buzzwords. → Insufficient Quality as Driver of Change
• Change scenarios describe the desired effect of modifying or extending the system or its environment. → Insufficient Quality as Driver of Change
• The document states which data and system state must be protected from unauthorized modification or deletion. → Integrity
• The document states how the system is split into discrete components so that a change to one has minimal impact on others. → Maintainability
• Each modifiability scenario describes one specific change, not a general wish to be easy to change. → Modifiability Scenario
• Each scenario names the stimulus, the system affected and the response. → Modifiability Scenario
• The document names the safe parameters or safe states within which the product must keep operating. → Operational Constraint
• Production monitoring covers business transactions and technical metrics such as CPU, latency and requests per second, with real and synthetic transactions. → Performance Efficiency
• Each performance scenario has a measurable response measure, such as a time limit or a percentile. → Performance Efficiency Scenario
• Quality requirements are written as specific, measurable scenarios, not as vague terms like “high quality”. → Quality Attribute
• Quality requirements have their own section, and architectural decisions refer to them. → Quality Attribute
• Quality goals were checked against both a short attribute list and the larger ISO 25010 list, so topics such as compatibility are not missed. → Quality Attribute Coverage in Bass et al.
• Safety is considered as a quality goal where physical harm is possible. → Quality Attribute Coverage in Bass et al.
• The introduction lists only the top three quality goals, and no more than five. → Quality Attribute Prioritization
• Each top quality goal has at least one concrete scenario. → Quality Attribute Prioritization
• Every scenario names a response measure, meaning a metric or criteria to judge the response objectively. → Quality Attribute Scenario
• Each use-case-specific quality requirement names the functional requirement it applies to. → Quality attributes in use case descriptions
• The document states which meaning of MTTR (respond, repair or recovery) it uses. → Recoverability
• Reliability goals name the specified functions and the specified conditions they apply to. → Reliability
• The document covers each sub-characteristic: faultlessness, availability, fault tolerance and recoverability. → Reliability
• The document states which operational hazards exist and how the system limits its operation to safe parameters or states when they occur. → Safety
• Confidentiality requirements state who may access which data, using need-to-know (least privilege) access. → Security
• Quality attribute names in the document are backed by scenarios that are specific and measurable. → Standard Quality Attribute List
• Qualities missing from the standard list, such as deployability, were considered where relevant. → Standard Quality Attribute List
• Testability is listed as a quality goal where changes to the system are expected, with its link to risk reduction. → Testability
• The document states which usability aspects matter (for example learnability, efficiency, error minimization) for the key user tasks. → Usability
• Each scenario is concrete enough to decide whether it is fulfilled. → Utility Tree
• Each quality scenario is specific and has a measurable criterion. → Working with Tactics and Quality Attributes
• The stakeholder overview names the customers and partners that appear in the business model. → Business Model Canvas
• If a canvas is cited, it is dated and versioned. → Business Model Canvas
• The introduction lists only the top 3-5 quality goals. → Business Model Canvas
• The document has an explicit stakeholder overview, so no surprises arise later in development. → Stakeholder
• The stakeholder overview lists roles, names, and their expectations about the architecture and its documentation. → Stakeholder
• Every stakeholder class has a representative, so no class is ignored. → Stakeholder
• The document lists stakeholders in a table with role or name, contact and expectations. → Stakeholder Identification
• Each stakeholder is linked to concerns, and the concerns are addressed explicitly. → Stakeholder Identification
• Every stakeholder class is considered, for example acquirers and assessors. → Stakeholder Identification
• The main stakeholders are identified and listed. → Stakeholder Power Grid
• Each stakeholder’s power to affect the project, positively or negatively, is assessed. → Stakeholder Power Grid
• High-power, high-interest stakeholders are named as key players and engaged closely. → Stakeholder Power Grid
• The documentation has a stakeholder table with roles, names and expectations. → System Idea and Vision Elements
• The vision statement summarizes the intention and motivation of the idea. → System Idea and Vision Elements
• The vision is short and fits in a brief statement or slogan. → Vision Statement
• The target customer group is named and is clear-cut. → Vision Statement
• The statement shows why people will want to use or pay for the product. → Vision Statement