Alphas of project decisions

A clearer way to structure decision documents

All project decisions that are worth documenting are architectural decisions because decisions about the organisation (or the ways of working) are architectural relative to the organisation (or the project) as a system itself.

We can think about most decisions as initiating small (or not so small) projects of carrying these decisions out in the context of the "main" project, or across interacting projects (e. g. projects sharing people or other organisational resources, or projects of creating systems that interface with each other). Therefore, it seems reasonable to reuse the alpha framework (see the reference frames of project alphas) to structure our thinking about these decisions, which includes writing decision documents, discussing them, and, ultimately, making the decision.

I take many alphas ("sections in the decision document", i. e., important objects of attention in thinking about a decision) directly from Jeff Tyree's and Art Akerman's "Architecture Decisions: Demystifying Architecture" (see also my summary), but structure them in a new way.

Here're the alphas of an (architecture) decision, with titles slightly modified relative to the alphas of a project:

Tyree and Akerman suggested a rule of thumb for deciding when an architecture decision warrants documentation (the amount of the documentation should be adjusted to the impact of the decision):

To test a decision’s architectural significance, an architect should ask the following question: does this decision affect one or more system qualities (performance, availability, modifiability, security, and so on)? If so, an architect should make this decision and document it completely.

Stakeholders

The stakeholders of a decision should be a subset of the stakeholders of the project if the decision is made in the context of a single project, or, if the decision affects multiple projects, a subset of the union of the stakeholders of these projects.

For each stakeholder, document their areas of concern that are affected by the decision, and their preferences in these areas of concern.

Each stakeholder has a status: "Doesn't need to be informed" / "Informed that decision is being discussed" / "Involved in the discussion" / "Shared their feedback or preference" / "Informed about the decision" / "Informed that the decision has been implemented" / "Informed that the decision has been obsoleted".

Issue/Opportunity

The standard project alpha equivalent to this one is called "Opportunities". I use the word "issue" and singular form to highlight that decisions are often made to address issues rather than seize opportunities. Also, decisions usually address only a single issue or an opportunity, or, to put it in another way, it's often a bad sign when people try to solve multiple issues or seize multiple opportunities with a single decision (Russian proverb: "за двумя зайцами погонишься, ни одного не поймаешь").

Sub-alphas:

• Issue (problem, subject matter). Explain the urge for making the decision (rather than deferring it for later, which should be the default strategy): “Describe the architectural design issue you’re addressing, leaving no questions about why you’re addressing this issue now.” This alpha is also sometimes called "Goals".

• Implications. Describe (try to predict) counterfactually how the situation with the issue (opportunity) will unfold if either of the decision options is chosen. How other related issues and opportunities will be affected? For example: "if the team spends resources on this issue, it won't have the resources to seize that other opportunity". There are always at least two possible options: "do something" and "do nothing", often more: "plan A", "plan B", "plan C", "do nothing".

• Non-goals/Scope. Describe what is in the scope of the decision and what is out of scope explicitly.

• Related decisions.

• Relevant principles. “If the enterprise has an agreed-upon set of principles, make sure the decision is consistent with one or more of them. This helps ensure alignment along domains or systems.” I think that industry best (state-of-the-art) practices or prior experience (within the team, personal, or found online) could also be referenced here. The project alpha roughly equivalent to this one is "Innovations".

Description

The standard project alpha equivalent to this one is called "System Description".

Sub-alphas:

• Constraints (boundary conditions): organisational, human, schedule, cost, risk constraints, non-functional requirements, alignment with the business and technology strategy. The project alpha equivalent to this one is "Architecture requirements".

• Relevant requirements. Show how the decision is driven by the objectives: “Decisions should be business-driven. To show accountability, explicitly map your decisions to the objectives or requirements. If a decision doesn’t contribute to meeting a requirement, don’t make that decision.” The project alpha equivalent to this one is "Requirement to the system" (note the difference from architecture requirements/constraints: they affect the whole design of the option chosen, not just the details).

• Descriptions of options (alternatives, positions, solutions, approaches). For each option, the following things are documented:

  • How the system (to which the architecture decision in question is applied) is changed (or not changed).

  • How the system properties will change in the relevant areas of concern of the decision stakeholders.

  • The migration plan, including the descriptions of transient and scaffolding (in one word: enabling) systems that should be built or bought just to carry out the migration.

  • The work plan.

  • Estimates of the resources needed to carry on the work plan (days of work, calendar time, money, etc.).

  • Risks: could carrying out the option fail?

• Conflict. What conflict is baked into the decision (every important decision has it)? How the conflict is addressed (drawbacks mitigated)?

Context

The standard project alpha equivalent to this one is called "System".

Sub-alphas:

• Descriptions and data (metrics, evidence) related to the involved system(s), especially their current de-facto state rather than "ideal" state (supporting "Constraints", "Implications", estimates in "Descriptions of options", and other alphas). Some examples:

  • Actual working practices (when making a decision about changing working practices), or actual communication issues (when making a decision about changing the organisation structure).

  • if the "Issue" of the decision is "Improve the security of the website", then the hard facts would be the descriptions of past security incidents (breaches), or statistics of incidents if there were too many to describe them all.

• Existing plans, responsibilities, obligations, and decisions that are already carried out by the "Crew" of the decision (see below) or within the projects affected by the decision.

Work

Sub-alphas:

• Works related to the decision itself: finding and documenting facts, analysing the issue, synthesising options (alternatives, solutions), discussion and decision-making sessions, informing stakeholders.

• The detailed work plan (estimates, schedules) of the chosen option (solution). The shorter version of this plan is also a sub-alpha of "Descriptions" before the decision is made.

  • Tickets, work items

• How the plan affects other plans in the affected projects?

Crew

The standard project alpha equivalent to this one is called "Team". I use the word "crew" to highlight that the decision discussion (and, possibly, the project of carrying the decision out) is more transient and probably has a well-defined finish line. It's more like a "movie crew", or a "ship crew", a "gig", unlike the project "team", which is thought to be more permanent.

Sub-alphas:

• Roles

  • Decision-maker (or a committee, if the decision is made by a committee)

  • Project and stakeholder representatives

  • All engineering and management roles necessary to carry out the decision

• People

Roles and people alphas have the same statuses as the equivalent alphas of the project.

Method

The standard project alpha equivalent to this one is called "Method of work". I drop the "of work" part because it also includes the method of decision making.

Sub-alphas:

• Method of decision making: "decider after discussion", "delegated to implementers", "consensus"? See good decision-making processes.

• Method of work: this is equivalent to the entire project alpha "Method of work" if we consider carrying out the decision a project in itself. For example:

  • If the decision affects multiple projects that use different methods of work (issue trackers, communication medium, etc.), how the work of the crew is organised?

  • How the stakeholders are notified about the progress?

• What metric of feedback loop will help to verify that the decision is effective in the future?