Solution Architecture Knowledge Transfer Checklist

Knowledge Transfer is a process of handing over all the important information from a current personnel to a new team. It also happens when a single member of the team is coming to a project.  

Why bother?

Failing a knowledge transfer causes consequences of different severities. The innocent one can be a delay of project evolution, however I faced losing a whole project and a major risk of losing the client in my personal experience due to the improper knowledge transfer.

In particular KT gives an ability to hand over the important pieces of information to ensure the continuous work on the project, avoid mistakes or production issues.

Obviously the particular topics to hand over depend on the position of a new person. This article covers what a Solution Architect needs to obtain or transfer to onboard successfully.

Knowledge Transfer is also a necessary and powerful tool to keep all the involved parties on the same page. People working on the project should now, what technical decisions are made, the reasons of those decisions, the changes to the architecture and to the different processes.

Level of Details

As this is more like a checklist, please do not expect a low level details. The idea is to have a flying bird level of understanding what is required to gather during KT process.

The good idea would be to schedule a meeting per each of the points in order to pay enough attention to every aspect of the knowledge transfer.

Table Of Contents

• People
  • Org Chart
  • Project Stakeholders
  • Teams
• Handover
  • Reasons
  • Expectations
• Requirements
  • Functional Requirements
  • Non-Functional Requirements
  • Constraints
  • Architecture Significant Requirements
• System Architecture
  • Diagrams
  • Components
  • Data Storage
  • Deployment Approach
  • NFR Testing
  • Decision Log
• Processes
  • Planning Processes
  • Development Processes
  • Release Processes
• Future Plans

People

Org Chart

Solution architect communicates with different people a lot. Understanding the roles of those people and their place in the corporate hierarchy provides necessary context.

There are different organization structures, but you need to understand which one you are landing, how your particular project or projects portfolio affects the success of the organization.

Project Stakeholders

Every project has it's stakeholders, as we figured out previously. Solution Architect has to know the list of them for several reasons:

• Know the people who make the decisions
• Know the people who are impacted by the decisions
• Know what, when, how and to whom to communicate the issues
• Know who to clarify the system requirements
• And many more

Plain Lists rarely make a great use. RACI matrix though makes more sense.

Teams

Some approaches include development teams in the list of stakeholders. In my opinion it is beneficial to understand the team setup. This is important, because different projects can follow cross-functional teams approach, or functional specific(Frontend Team, QA team, etc).

• Set of development teams
• Contacts of each of the team leads
• Size and velocity of each of the teams

Handover

Reasons

As a first item, you would like to understand why the handover happens in a first place. Possible reasons are:

• Solution Architect is leaving the project
• Tech stack is changed due to new requirements
• The current requirements are not fullfiled

Expectations

In the context of a handover you need to understand what do stakeholders expect from a new architect.

Requirements

Solution Architect role is crucial in ensuring the system will fullfil it's requirements. Architects distinguish Functional Requirements, Non-Functional Requirements and Constraints. In case you are not sure what it is there is a short guide here. Set of requirements and constraints is a primary input for an SA. During Knowledge Transfer make sure you have those.

Imagine, we are building a messenger app. Let's see the requirements examples.

Functional Requirements

Typically, the Functional Requirements for the system exist in the form of User Stories. Stories can be tickets of a special type in any bug tracker software like Jira, Redmine etc.

Imagine a user stories for sign up:

Title: As a user I would like to sign up so that I can use the messenger app.

Acceptance Criteria:

1. If a user has not logged in yet he/she is prompted with sign up window
2. Sign up window includes the description, a phone number input field and a button
3. Sign up button is disabled until the phone number is correct
4. Once the button is pressed the app should send an SMS message with one-time code

This is a very raw form of a story, but provides necessary details.

Non-Functional Requirements

Non-Functional Requirements can be tickets as well. In my practice, NFRs are written in a form of a table. It should have a key, a description and an area.

• Key is a unique string, identifying the requirement, like ABC-21
• Description is the requirement itself, like "The system should be highly avaiable with %99,99"
• Area is the quality attribute name we are talking about. Availability, Security, Performance, etc.

The table of Non-Functional Requirements would look like this:

ConstraintsConstraints are the requirements which you can not change or even negotiate. For example, you have to respect laws of the country your system will operate in. Or, the organization you work about is already using some technologies which it is not willing to change, like .NET or others.

Constraints are also tracked in a form of a table.

Architecturally Significant Requirements

Not every requirement affects the architecture. Architects look firstly in those which do. They are called architecturally significan requirements. During knowledge tranfer you're interested firstly in those requirements. If they are not identified, you would like to know how to fix this.

System Architecture

Diagrams

From Software Architecture in Practice, we know that

The set of structures needed to reason about the system, which comprises software elements, relations among them, and properties of both.

We also know there is no a single form to sufficiently describe the system architecture. Instead we look at the system from different view points and get different views.

The minimal set of views is the following:

• Context diagram
• Components and connections diagram or Container Diagram
• Deployment Diagram

Speaking about my experience, I typically use around 5 diagrams to document the systems I work with.

Components

Every system can be split into components. You will find them on the diagrams listed above. A component can be almost any deployable unit: a CMS installation, a microservice, a web application, a database or a mobile application.

For every component of the system you would like to know at least:

1. Purpose of the component
2. Technology stack
3. Component's Architecture Approach
4. Source code storage link

Assumptions

Every architecture is built with some assumptions in mind. They affect the architecture significantly. You need a list of those assumptions indeed.

Data Storage

Every system accepts, process and stores the data. You need to understand, how the data is stored:

• Set of databases
• Databases schemes if applicable
• Databases technologies
• Purpose of each of the databases
• Sharding and partitioning approach for them

Deployment Approach

It is highly important how and where the system is deployed. The answer to "where" should be covered by the Deployment Diagram, mentioned above. Here you would like to know how parts of the system get deployed there. For example:

• Is each of the component can be deployed in a single click
• What is the technology for the deployment pipelines
• Where the pipelines can be found

NFR Testing

The Non-Functional requirements which are gathered above should be tested to ensure the system actually fulfills them. You would like to know what test systems are in place and what they allow to test.

Solution Architecture Decision Log

Every system evolves with time. The architect and the development teams can make the decisions to change the architecture almost every week. The good architecture practice is to document those decisions. The reasons for it are:

• Explain your future self why you did something in a particular way
• Improve knowledge transfer
• Log the alternatives to the decisions you made

Where to get

Architecture is a complex topic: a lot of information is required. There are different approaches how to properly document that. I am using a Solution Architecture Document approach. If you have a link here, then you're lucky - I published the article about it. If not, don't forget to subscribe to get notified once I publish it :)

Processes

Planning Processes

You will need to understand how the teams plan their future work. Some of the questions to check:

• Is there a backlog somewhere?
• Does a regular planning meeting happen?

Development Processes

Development processes are important as well.

• Do you have CI in place?
• Do people write unit tests?
• Do you have static analysis in place?
• Can you deploy a component in a single button click?
• Do you perform architecture design before feature development?
• Do people write automated end-to-end tests?
• Do people perform refactorings regulary?
• Is technical debt measured and fixed?
• Is there a README.MD file in the root of each repository?

And many more.

Release Processes

• What is the procedure of approving the release?
• What are the steps the software should go through in order to be release?
• Who is responsible for pressing the buttons?
• Where do the release notes are published?
• How do the deployment pipelines look like?

Future Plans

Your system is going to evolve. It is highly valuable to know where your system will  go in future. You would like to have a Roadmap for the product.

From the business perspective, you want to know the business drivers and how they affect your system. It will be extremaly dissapointing not to pay attention to the performance and scaling if you're planning to double the user base next year.

Summary

This checklist is a work in progress. I believe it is already useful for Solution Architects ramping up on a new project or onboarding a colleague to the existing one. It will allow not to miss any big parts. If I missed anything or made a mistake, do not hesitate do leave a comment down below 👇

I also created a github repo with the checklist. You can contribute your thoughts there!

Also, if you liked the article, make sure to Subscribe to get notified once a new article is published. Sharing the article in your social networks are always welcome as well.