Skip to content
academia.sh
tr
Log in

Course Intermediate

Architectural Decisions and Documentation

By the end of this course

Start course

01

The Decision Record

Leaving a trace of the decision: the structure of architecture decision records with context, decision, and consequence fields, the effect of a written-proposal culture on the evaluation process, alternatives eliminated by scoring along quality axes, a risk register that tracks uncertainty through likelihood and impact, and deliberate and inadvertent technical debt measured separately.

  1. 01 Architecture Decision Records Recording a decision with context, decision, and consequence fields: the questions someone asks six months later are modeled as a question set, the same decision set is run against that set in an unrecorded and a structured recorded scheme, the answered and unanswered questions are counted, the cost of writing the record is measured in lines and minutes, and whether the superseded-decision field keeps the old decision readable is counted.
  2. 02 The Proposal and Evaluation Process Measuring how a decision gets made: the same decision set is run through verbal approval and through a written proposal plus an evaluation round, the rate of decisions that change direction under evaluation, the number of rounds, the number of roles involved, and the time elapsed are counted, a question set is applied to the record the process leaves behind to separate a correct, missing, or wrong answer, and the decisions the written process only delays are measured.
  3. 03 Trade-Off Analysis Measuring the recorded state of the table where alternatives are scored along quality axes: whether a third person can arrive at the same result from the recorded table is counted, a missing criterion, an unwritten weight, and an unsourced score are separated as three distinct flaws, each flaw is fixed one at a time to measure the rate of reproducible decisions, and the cost of completion in minutes is computed per gained analysis.
  4. 04 The Risk Register Tracking uncertainty through a record: risks are modeled with likelihood and impact, a period is run with a generator whose seed is visible, the recorded likelihood estimate is compared against the measured realization rate in bands, risks that occur despite never being recorded are counted, and the effect of review frequency on the number of risks caught before they occur is measured along with its person-minute cost.
  5. 05 Technical Debt Management Separating and measuring deliberate from inadvertent debt: debt items are split into two classes, debt interest is modeled as the difference in work the same change causes in an indebted module versus a debt-free one, yearly interest per item and the rate of extra work per module are computed, the delay before inadvertent debt is noticed is measured as a function of a repeat threshold, and the interest paid unnoticed across that delay is counted.

02

Views and Models

Which picture answers which question about the system: the logical, process, development, and physical views each answering separate questions, the layered diagram approach that changes scale from context to code, selecting the diagram type by question, turning quality requirements into measurable scenarios, keeping the document in step with the code, and size estimates given with an uncertainty band.

  1. 01 Architectural Views Applying a question set to the logical, process, development, and physical views: how many questions each view answers, the class of question no view answers, the repetition where two views answer at once, and how many questions are missed by settling for a single view.
  2. 02 The Layered Diagram Approach Modeling the same system at the context, container, component, and code level: the number of nodes and edges per level, the level at which a question gets answered, the unnecessary nodes a reader looking at the wrong level reads, and the break-even point of keeping four levels in maintenance.
  3. 03 Selecting the Diagram Type by Question Mapping the structure-showing, sequence-showing, state-showing, and deployment-showing diagram types onto a question set: the correct type per question, how many information items are left missing when a question is answered with the wrong type, and how many items each type has to update per code change.
  4. 04 Quality Attribute Scenarios Writing a quality requirement so it can be tested: the same twelve requirements written in plain-sentence and fielded-scenario form, counting how many of each come out testable, turning the empty fields into questions, and measuring the disagreement an unwritten threshold causes at delivery.
  5. 05 Keeping Documentation Current Actually measuring documentation drift: comparing the reality extracted from a module import graph against the document's claim, watching the drift grow across eight changes, and comparing three keeping-current regimes by the drift they catch, the maintenance cost they impose, and the false alarms they produce.
  6. 06 Estimation and Evaluation Measuring work-size estimation: the same set of work estimated as a single number and as an uncertainty band, then compared against what actually happened, the deviation distribution's percentiles, the band's actual coverage rate, and how splitting the estimate into pieces changes both the deviation and the spread.

Start typing to search.

↑↓ ↵ Esc navigate · open · close