Software Team Member Onboarding

I work routinely as a freelance software architect helping clients with their software projects. There’s a certain sameness to coming onboard a project. There are a ton of questions to which I need answers as I try to come up to speed. It’s often hard to know where to start.  I’ve put together this guide for me and my clients to help smooth my on-boarding process.

Multiple Project Views

I prefer not to think of the problem of coming up to speed as getting answers to a bunch of questions. I like to think of it as building multiple mental models of the project, each of which is a different view of the project.


Below is the list of the views I build.  It’s presented in roughly the same order that I assign priority; I start at the top of the list and work my way down.  I don’t try to complete any of the view.  I iterate through them adding to each as needed to do my work.

  • Contact list
  • Organization Chart
  • Business Plan
  • Road Map
  • Software Architecture
  • Software Development Process
  • Idea Pipeline
  • Code Pipeline
  • IT Infrastructure

Detailed Project View Descriptions

For each view I describe why I need the view and give an example of a tool that might be used to capture the information in that view.

I give the tool as examples only in order to make the discussion less abstract. Ultimately what’s important is that I am able to create a mental model of the project so that I can contribute to it effectively and so my client and I can talk about the different aspects of the project.

Contact list

This view is at the top because first and foremost I must to be able to communicate with your team members.  If I know nothing other than how to contact my other team members then at least I know enough to start learning.

A tool for this is something like Slack. There are other communicator type tools, like skype/google hangout/facetime etc.  They work, however they are not really team oriented communication tools.

A dumbed down version of a tool for this view would be a simple contact list with phone numbers and emails.

Organisation Chart

Even if I know who is on my team I may not know who knows what or who is responsible for what.  The organisation chart, combined with the contact list, helps me figure out who to contact.

A graphical org chart, available on a webpage, with the names of the teams, people, and responsibilities is usually enough.

Business Plan

A simple business plan gives context for making difficult decisions. It tells everybody at a high level what we are trying to do, for whom, why and the cost/benefits of it.  I like to start with this view of the project when I first interact with a prospective client in order to understand their goals.

A one page business model canvas is what I mentally think of when I think of a business plan.  It has the important answers for the team all on a single page. I prefer the lean canvas variant.


Road Map

A road map gives a timeline of how the business plan will come to be realised.  It shows on a timeline what the ‘A’ priority events and the ‘B’ and ‘C’ events are along that timeline.  It tells me the plan for building team confidence and demonstrating to stakeholders the project is on track.

A simple picture of a timeline showing the timescale of the plan, where the important events are on that timeline and then below it  some detailed text describing what’s shown in the graphic.

Software Architecture

This is possibly the most abstract and least understood item on the list.  It describes a model of the software that is being built.  At the most basic level it provides the vocabulary that people use to talk about the problem and the solution.  It tells how the bigger problem has been broken up into smaller decoupled problems and how the architecture helps manage risk.

I use the 4 + 1 architectural model to organise my thoughts/questions and to communicate my understanding of the architecture to other team members.

The “+1” refers to a description of the users and capabilities the system gives those users. That’s where I start to build the architecture. It gives an idea of the system tests the implementation will need to be able to satisfy.

The model can be captured in simple documents which coexists with the source code, on a wiki or in a modelling tool.  It differs greatly from project to project and also depends upon the team’s experience.

Software Development Process

This describes the process by which the team takes ideas and transforms them into customer value.  It tells me the life-cycle of an idea and the roles of the team members who work to move the idea along.

It also describes how the cadence of the project is set and measured.  I’ve found attention to project cadence to be critical in getting feedback and correcting problems rapidly.

I prefer lean development (just in time manufacturing) and agile ones.  In particular I favour SCRUM with KANBAN.

Idea Pipeline (Work Item Pipeline)

This tells me what is in the backlog of ideas (user stories/capabilities) that are to be implemented.  It enables me to analyze the work-in-progress, who is working on what, the team’s capacity to do work, the team cadence, what has been queued up to be worked on next, the priorities of what is to be worked on next and what has recently been completed.

At a high-level it begins from a lean business plan and a few customer personas.  The  goal is to develop/implement a customer journey. The process can be one of Story Mapping and Issue tracking.

A combination of two tools such tool as StoriesOnBoard and Jira works.  Important is that the tools enable designing a customer journey,  a minimal viable product, backlog management, work item priority setting, story breakdown and work-in-progess visualisation.

Code Pipeline

The code pipeline describes how a developer’s software changes move from the developer’s development environment to the production environment.

For example, the software changes would typically undergo some local testing, be committed to a source control tool, undergo some more testing in a staging environment and then eventually be deployed to a production environment.

An example of a Code Pipeline is the AWS Code Pipeline provided by the AWS (Amazon Web Services).  An example of a Source Code branching model is the Gitflow branching model.  A nice graphical tool for working with a GIT source code repository and which can help implement the Gitflow branching model is GitKraken.

More generally the pipeline consists of a set of tools: source control (e.g. GIT), build tools (e.g. Gradle, Ant, Maven) and a continuous integration server (e.g. Jenkins).

IT Infrastructure

The IT Infrastructure  tells me how all of the other views exist on physical computing resources.  This view tells me the IT infrastructure/tools needed to support the project and how the team members interact with that infrastructure/tools.

Modern cloud infrastructures allow a lot of the IT infrastructure to be setup, replicated, and torn down automatically with a few click of the buttons.

For example, the AWS Cloud Formation tool enables a IT infrastructure for code pipelines, staging and deployment to be described formally and setup/torn-down automatically with a click of a button.

Another example is the AWS Workspace Tool that enables developer machines to be designed, replicated and deployed at a few clicks of a button. This makes it possible to setup a developer environment within minutes of a developer coming onboard a project.