Architecture Deliverables Governance Framework [ AGDF ]

Requirements Management

Document Purpose

The goal of this document is to set a framework on how to handle the architecture deliverables ( Solution Design Document, Technical Design Document, LLD)? throughout SDLC,? starting from feature/user story ellaboration , through solution document creation, approval and sign-off after review with the development teams. ? This document also covers the architecture change management side, which documents the process of changing an already signed-off architecture deliverable.

This document sets a framework, which establishes ways of work between the technical architect, the solution architect, the product owner (PO), and the development teams, and tries to document the interactions between them based on best practices.

The ultimate goal of this framework is to ensure solution end-to-end alignment, between PO, architects, and engineering teams so that a common vision is shared across.? ? Alignment ensures the aiming of everyone to the same goals and helps to get more consistent results in terms of software quality and software completeness, as we as ensuring what’s being built is aligned with the business expectations and goals.

In many organizations, there could be many pain points from management in terms of how deliverables are being created, and at which level they are aligned with expectations, or how change management is being implemented if, for some reason, requirements are changing over time, which may impact not only solution design but also the implementation itself.? ? By setting standard validation mechanisms the primary purpose is to mitigate such pain points and establish a more solid and robust way of handling requirements.

Intended Audience

This document is primarily intended to be read, stored, distributed and adopted by different multiple IT teams that are daily working – directly or indirectly –? and involved on the SDLC directly with requirements definition, requirements elaboration,? validation,? solutioning,? and implementation.

• Solution Architecture
• Engineering / Development
• Product Owners (POs)

Handling Requirements through SDLC?

Requirements ideation and elaboration

Whereas product definition falls within the Product Manager(PM)/ Product Owner (PO) domain, elaboration of digital products through Agile methodologies in the form of feature / user stories necessarily requires a direct interaction between the PO and the Technical (TA) / Product Architect (PA) .? A ? technical architect / product architect will take ownership on validating requirements in terms of:

?

• Feasibility:? how feasible the requirements are in terms of the existing technology stack,? existing cloud environment,? existing limitations and restrictions from the technical side that may be limiting what can be done.
• Correctness:? how correct are the user stories being documented in terms of the functionality /capability being documented ? In other words, the user stories should reflect what is coming from the business requirements completely with ideally zero gaps.
• Acceptance Criteria: ? we should necessarily provide acceptance criteria so that engineering can validate against what is expected from the user story outcome once built.? ? User stories without acceptance criteria will cause a lot of struggle from the engineering side once they have the user stories in front of them.
• Completeness:? ? the user stories should be complete enough so that proper solutioning can be established. Architects must ensure that the user stories being written are enough completely documented and described, removing any possible gap that may lead to misunderstanding or doubts.
• Architecture Quality: ? user stories must be shaped with architecture quality in mind. ? Concepts such as usability, extensibility, and scalability must be considered even when designing user stories, especially when designing backend-oriented solutions. ? By designing a product with quality in mind from the very beginning, we ensure a solution design that will be aligned with those principles.

User story and feature elaboration should be a joint work of PO and? the technical / product architect ( TA / PA ) , where discussions are also expected to happen in order to ensure the above points.????

Solutioning and Solution Approval Flow

Once user stories are formally signed by PO, the architect may start delineating the high-level and technical architecture that would satisfy the requirements. ? The technical architecture document (TAD) or also called BluePrint / Solution Design shall be initially in the DRAFT state.

It’s recommended to keep the Solution Design document scoped to a single feature, both to avoid lengthy documents, and also for better solution design mapping to requirements.

A solution in DRAFT transitions into a READY-FOR-REVIEW once the architect considers that his solution is complete. ? In such a case, the architect must submit the document to the Solution Architect (SA) for review.

For that purpose, a meeting must be set so that the architect can better explain the feature being covered, their user stories, the high-level architecture and technology stack, and the approach itself.??

?

As a result of the revision two things may happen:

• The SA decides that the solution is ready, and does not require any further modifications, and can be delivered as-is.
• The SA decides that the solution is yet not complete, and hence requires modifications in order to get to a good shape. ? In this case, the architect must work the document by incorporating any of the recommendations given, and hence,? perform another review meeting with the SA.
• A second review occurs, and SA needs to evaluate the approach once more. ? Usually, no more than two reviews are required but if more are required, then multiple review cycles can be conducted ( i.e. specially on long solution designs with bigger features )
• Once the solution becomes approved by the SA, the Solution Design transitions from READY-TO-REVIEW to REVIEWED.
• The SA decides that the solution is not feasible for any reason, or foresees that for any reason, it’s not going to be possible to get implemented. ? In such a case, the Solution Design document must be transitioned into NON-FEASIBLE, and a further review meeting must be set between the Solution Architect, the Architect, and the Product Owner, in order to align the requirements based on the feedback provided by the Solution Architect.
• As a result of this meeting, the following can happen:
• The Product Owner assumes that it’s not feasible and removes the functionality associated or gets it modified so that the Solution Architect's concerns are satisfied.? This will trigger further changes in the solution design.? In this case, the solution design can be transitioned first into the SD-UPDATES-PENDING state, indicating that the architect is working on introducing the required changes in order to satisfy the changes required at the feature/user story levels. ? Once done, the SD must be transitioned into the READY-FOR-REVIEW state, and hence, it will go through the approval flow again.
• Feature/user stories may require revision with Product Management since the functionality required cannot be removed from the product roadmap due to high-level business requirements.

Cycling the Solution Design with Engineering

Once a solution design is in the REVIEWED state,? then a walk-through session must be established with the engineering/dev teams in order to explain the scope, approach, high-level architecture, components, technical stack, limitations, and expected outcomes.

As a result of the review, the engineering team may come with gaps or areas where documentation must be enhanced for better understanding. ? Also, engineering could criticize the design in terms of not being doable due to some constraints;? as part of this discussion, the architect will evaluate and consolidate the feedback.

Sometimes, as a result of a review with engineering, the Solution Design document may result in being modified in order to incorporate the feedback given, if the architect considers it necessary, and then, another second review round is set with engineering for re-evaluation.?

When that happens, the SD document is transitioned into the SD-UPDATES-PENDING state while the architect is making changes in order to incorporate details asked by engineering. ? Once done, the SD must be transitioned into the READY-FOR-REVIEW state.

Multiple reviews may occur with engineering, as required.

The review is considered to be completed if and only if:

• No gaps have been detected from the High-level solution design
• No technical concerns/limitations raised
• The High-level solution design has been determined to be feasible from the implementation point of view
• The team has understood completely the approach, with no knowledge gaps

In such a case, the Solution design is said to be in SIGNED-OFF state, which has been signed-off by engineering as well from the feasibility/implementation point of view.

A signed-off Solution Design is considered ready for development and can be handed off to engineering in order to start building it.? Once the engineering team starts working on it, the Solution Design is said to be in the IN-DEVELOPMENT State.

Architecture Change Management

How to Handle Changes?

Architecture change management is the ability to handle changes to the Solution Design document, once it has transitioned into the IN-DEVELOPMENT state. ? ? Solution documents that currently are in the IN-DEVELOPMENT state are currently being translated into a concrete implementation by the engineering team, and thus,? any change on it may impact on the actual work being done,? or work actually already done.

Changes to an already signed-off solution design may happen because of :

• The Product Owner decided to quickly introduce some changes at the feature/user story level due to an urgent business requirement that wasn’t considered initially as part of the Feature set, which led to necessary changes on the solution design by the architect.
• The architect itself decided to introduce some changes on the architecture approach due to some architectural gap seen that was identified only after the solution has been signed-off.
• During implementation,? engineering detected some blockers that led to a necessary change on the solution design in order to solve that blocker by applying a different approach/strategy.???

Let’s discuss the three scenarios and how these should be managed by following the proposed architecture change management approach

Product Owner decided to introduce changes

Any change introduce by a PO after the solution design has been signed-off,? will necessarily require a review meeting between the architect and the PO; ? the architect must evaluate the change as if it were a new user story to consider, in terms of feasibility/correctness/acceptance criteria.???

Once an agreement has been reached between PO and the architect, then the architect must proceed to incorporate such changes into the Solution Design document.? ? Once the document has been modified, it needs to transition from SIGNED-OFF or IN-DEVELOPMENT to the SD-UPDATED-PENDING state, so that the architect can work on introducing the necessary changes at the solution design level in order to satisfy the changes proposed by the PO at the feature/user story levels. ? Once done, the SD must be transitioned into the READY-FOR-REVIEW so that it can be reviewed again with the Solution Architect.

The changes proposed by the PO should already be reviewed by the product architect so that he/she can confirm the changes are feasible and can be implemented as expected.

The changes must be evaluated by the Solution Architect and approved by him/her.? The solution architect may:

• Approve the change, in such a case the Solution Design document transitions into the REVIEWED state, and then, follows the standard engineering revision process, on which the architect will be cycling the changes with the engineering team for better understanding of what has been changed and why. ? Depending on the progress from engineering, it may involve re-engineering the existing implementation if the team already get implemented that portion of work that would require re-work.
• Do not approve the change, in such a case the solution Architect must provide reasons.? The architect must then challenge with the Product Owner,? by following the same approval process explained on the earlier section.

Once the changes have been approved by SA and the Solution Design becomes in REVIEWED state, then the architect must walk through the necessary changes to the engineering team in order to perform a full review of changes for better understanding.??

The architect itself decides to introduce some design changes

In this flow, the architect decides to change the solution design document due to underlying issues/concerns detected after the Solutiion Design has been signed-off.? It’s important to remark that this kind of change is usually at the technical level, not at the functional level, since otherwise it would qualify as a feature/user story change.

Technical changes are usually introduced to enhance performance, responsiveness, consistency, availability, scalability,? security, and extensibility or to enhance any other architectural quality attribute and are necessarily targeted to the technical level.

No functional (business logic) change or business capability change should be introduced by an Architect or come from an Architect. ? Such kind of changes must come from the PO only.?

While the architect is performing changes to the solution design, it must be transitioned into the SD-UPDATES-PENDING state.? Once all changes have been committed, it must be transitioned into the READY-FOR-REVIEW state, and hence, a full review process must be established between the architect and the Solution Architect, who should review the changes. ? As a result of this review, the following may happen:

• The SA. Decides to approve the changes, since those changes are not going to affect the existing business logic, and also contributed to a more robust and solid design, in such a case the Solution Design document transitions into the REVIEWED state.? ? Changes introduced must be discussed later with engineering ( following the typical approval flow), and once done, the document can be transitioned into the SIGNED-OFF state.
• The SA decides NOT to approve the changes because those changes are going to have a detrimental impact / because they are not aligned with high-level architectural guidelines, or simply because the changes introduced cannot qualify as a “technical change” but rather a “functional change”. ? Functional changes must necessarily come from PO. ? In such a case, the changes must be reverted back to the Solution Design.

Changes coming from within the development team

The development team can recommend some “tweaks” or variations on the implementation in order to improve it that may have an impact on the existing documented Solution Design.??

The architect must evaluate the changes and consider if those proposed changes are viable/necessary.? If the changes are considered necessary and are also viable, then the architect must incorporate them into the Solution Design. ? This change is going to be managed in the same way that a change is being introduced by the architect, as we explained in the above section.

Overall Workflow

State-Transition Diagram for a Deliverable

Conclusion

A proper architecture deliverables governance framework is a must for every IT organization.? ? Getting rid of it can lead to multiple pain points on the whole SLDC lifecycle including requirements not being understood or poorly defined, ? poor implementations,? a time-to-deliver being impacted due to multiple cycling between product, architecture, and engineering,? which leads to an overall reduction in the quality of the software being delivered due to lack of clarity of roles and expectations.??

The architecture deliverable governance framework (ADGF) presented here aims to straighten the whole process of product ideation, solutioning and implementation by providing a separation of concerns between product architecture, solution architecture,? product management, and engineering. ? ? Alignment between these áreas is highly important regarding the overall execution in terms of software quality,? solution completeness, and which is more important,? business goals alignment.

In bigger organizations especially those not mature enough, having a proper framework for handling architecture deliverables helps to provide visibility to everyone and overall alignment on top of the ways-o-work (WoW) that will provide better clarity especially when there are cross-functional teams working together in those bigger engagements.

As a solution/chief architect, we encourage you to implement this from the very beginning of a project. ? It’s the primary responsibility of the solution architect / chief architect to evangelize and make sure that everyone is aligned with the same vision,? and that must include engineering, product management, architecture, and customer stakeholders, and should be part of the architecture governance portfolio.