Architecture Analysis method

ARID (Active Reviews for Intermediate Designs)

Examines how well developers can use a preliminary design for their tasks.

ARID helps teams try out interfaces while a design can still change. The developers who will use them choose typical tasks and work through them together. They write code or pseudocode, a simplified description of program steps. This reveals which interfaces are easy to use and where descriptions of their behavior are incomplete or contradictory.

Core question

Can developers accomplish their important tasks using this preliminary design?

Create work plan Method guide

Start comparison

Give feedbackIs this method useful to you?

Participants: Designers, developers as users, and facilitation
Time: Use 2 to 4 hours as a planning range for a focused review meeting. Allow additional time for preparation and follow-up; total effort depends on the design and scenarios.

The five work sections group the nine original steps into preparation and a joint review. You can prepare the materials on your own. In the review, future users try out the design together.

Design sheets and interface cards connect to jointly written pseudocode with highlighted unresolved questions.

Prepare
Invite developers and prepare materials
Design owners prepare interfaces and examples for the joint exercise.
Introduce
Present the method and design
The group learns about the interfaces and how the active review will work.
Select
Collect and prioritize application scenarios
Reviewers contribute tasks from their work and select the most important together.
Exercise
Work through scenarios together in code
Reviewers jointly write calls to the proposed interfaces and record their observations.
Capture
Agree findings and the next revision
The group confirms the findings and agrees who will take the next steps.

Try the affected scenarios again after revising the design. Record resolved problems and scenarios still to explore.

A good fit when

For the preliminary design of a service, library or component. Developers who will use it take part in the review. The results show how well they can accomplish the selected tasks with the design.

Ideal for

Preliminary APIs and designs for individual system parts
Early feedback from developers who will later use the design
Trying typical development tasks before the detailed specification

Not good for

Full evaluation of the overall architecture
Acceptance by one person without involving the future users
Measurement evidence for performance or security

Outputs

Exercised application scenarios
Jointly written code or pseudocode with visible unresolved points.
Design findings
Specific usage obstacles and unresolved interface rules, each with an owner to address it.

ARID review record

Fictional teaching example

A document template for your review. A separate fictional example shows how to review a reservation library.

Design and reviewers

Enter the design version, boundaries, participating developers and review roles.

Reservation library v0.3; two consuming teams; Alex facilitates.

Scenarios and selection

Record tasks, priorities, selection reasons and scenarios still to explore.

Safe retry after timeout has highest priority; cancellation remains unexplored.

Code and observations

Link code or pseudocode to interfaces used, questions and assumptions.

After a timeout, it is unclear whether reserve(request) succeeded; calling it again could create a duplicate reservation.

Findings and revision

Record the usage obstacle, affected location, owner and repeat check.

Identify the request with an idempotency key and add a status lookup; then repeat the scenario.

The example illustrates the method using invented information.

Paul C. Clements: Active Reviews for Intermediate Designs (SEI, 2000)

First step

Choose the part of the design to review and invite its future users. Prepare interfaces, data types, expected behavior and examples.

Open the method guide

Good to do first

Architecture

C4 Model

Bounds the technical design and its consuming systems.

Where to go next?

Agile

Specification by Example

Turns clarified scenarios and interface rules into concrete behavioral examples.

Architecture

Request for Comments

Structures necessary design changes as a proposal with options and open questions for the next review.

Deep dive

Purpose

ARID examines how well developers can work with a technical design. It focuses on a part of the system that can still be revised, between the architecture overview and the detailed specification.

How it works

Prepare an introduction, a working usage example, and possible tasks for the design. Developers add their own scenarios and choose the most important ones. Using the available interfaces and documents, they jointly produce code or pseudocode for those tasks. Record their questions and difficulties as review findings.

In detail

ARID needs a preliminary design with sufficiently described interfaces, examples, and explanations for concrete development tasks. Designers prepare the materials. The developers who will later work with the design try it from their application perspective. This reveals missing information or operations and awkward usage. Facilitation and note-taking preserve the observations. The findings show how well the design supports the tasks examined. Performance, security, and the overall architecture are examined in separate analyses.

Facilitation

Select tasks from the developers’ future work with the design. Rehearse the introduction and example beforehand. Let developers add their own scenarios and observe how they solve them. Keep interventions by designers brief. Record each additional explanation needed as a point to address in revisions. One person can prepare the review. The active review requires the future users, the designers, and a facilitator. Allow time afterward to review the findings.

The method guide walks execution through 5 phases, timing, 5 pitfalls, and clear stop criteria.

Open method guide

Your perspective

Does this method help with your work?

Your feedback helps shape the next improvements to methodatlas.

Sources and topics

Topics

Architecture Engineering Feedback Validation Tasks

Sources

Paul C. Clements: Active Reviews for Intermediate Designs (SEI, 2000)sei.cmu.eduOriginal report CMU/SEI-2000-TN-009: intended participants, two phases with nine steps and joint application of design interfaces through code or pseudocode.Active Reviews for Intermediate Designs: Original report (PDF)sei.cmu.eduThe full report explains roles, nine steps, the joint coding exercise and limitations through the original pilot.

Artifact templates

ARID (Active Reviews for Intermediate Designs): WorksheetAllow time for preparation and a joint review meeting. Set the scope around the most important application scenarios.

markdown

arid-markdown.md

Allow time for preparation and a joint review meeting. Set the scope around the most important application scenarios.

ARID (Active Reviews for Intermediate Designs): Worksheet

Question

To be confirmed

Desired outcome

To be confirmed

Scope

Entire review Time: Use 2 to 4 hours as a planning range for a focused review meeting. Allow additional time for preparation and follow-up; total effort depends on the design and scenarios.

Complete this worksheet on paper or in your own document during the work.

Preparation for this scope

Method setup

Materials: Versioned design with interfaces, data types, expected behavior and examples; scenario list, shared editor and findings log.
Roles: Design owners, future users as reviewers, a facilitator and a note-taker. Agree who will answer scenario questions. Reviewers need programming and domain knowledge.
Advance information: Share design purpose and boundaries, interfaces and examples. Explain the reviewers’ active role.
Overall time needed: Use 2 to 4 hours as a planning range for a focused review meeting. Allow additional time for preparation and follow-up; total effort depends on the design and scenarios.
Setup: Keep code or pseudocode and findings visible together. Separate clarification from discussion of new design options.

Prepare for the work steps

Prepare: Invite developers and prepare materials

Bounded design
Design owners and developers who will use the design

Introduce: Present the method and design

Design materials and seed scenarios

Select: Collect and prioritize application scenarios

Understood design
Seed scenarios as prompts

Exercise: Work through scenarios together in code

Prioritized scenarios
Interfaces and examples

Capture: Agree findings and the next revision

Code or pseudocode and findings