Creating connected remote teams

Building a good team of developers is very hard, but building a good team of developers that like to share the knowledge and write good project documentation is even harder. In the world of Covid where many companies were left with no choice but let employees to work remotely from day to day all of them had to find a solution of how to share the project knowledge between team members and between teams.

This is the topic of the speech I gave at UXDX EMEA Community edition, on 14th of April, 2021.

The background

At my current work, together with my team, we're responsible for migrating the legacy codebase to a new tech stack. The new stack is based on Next.js, TypeScript and excessive testing on the frontend side, while the backend is based on serverless architecture and GraphQL data providers with a help of legacy backend codebase, still. The backend of this project is too huge to migrate it very quickly and yet it's not very well documented (as well as the frontend part), so we’re moving piece after piece.

The story of failure

It all began long time ago. A few years back there was a decision made to rebuild the project codebase following some new approaches. It was all going well until it stopped going well.

The project was growing, the new people were joining teams and nobody took care of documenting decisions and approaches. That led the project to a situation where each team was introducing own approaches to develop features and maintain it in the short-term.

It would not be even that bad, but people started leaving teams, joining other projects and still, there was no documentation. At the end, maintaining the project was like fighting with hydra. You fixed one bug, but two new were introduced because some potentially unrelated feature was broken.

And it happened at least twice, until my team took responsibility of setting up standards. Then everything started looking better and better.

The tribal knowledge

That's leading us to something called the tribal knowledge. Some of you might already heard about it. It's a knowledge spread vocally. There's no written document. You have to remember everything or you might fail because you forgot an important piece of that knowledge or whole at once.

Having the possibility to write down all the details of some particular solution is something that brought us from the stone age to the modern world. With technologies we have spreading knowledge, learning from it, understanding the processes in the past is something that we should make a use of from the day one when project is starting.

What can go wrong?

Ok, let's get back to the beginning where you don't have anything documented. What can go wrong?

You don't know why a given approach was chosen,
You don't know why such a tech stack is selected,
You don't know the features you implemented (long time ago),
You don't know how to move your business through the hard times,
Fellow devs will not know what can they use from existing codebase and they will duplicate the existing code, aka. reinvent the wheel - wasting their time,

How do we make the communication better?

In order to avoid such situations we have to stop and think how we can avoid such situations? How to improve communication within the team?

For remote teams clear communication is even more important than for the in-house teams. When working remotely you have no chance to see all the details of a team member's reaction. Most of times the communication is based on written sentences. Here we get to the point.

Real win - async communication

The real win here is the async communication. We try to avoid as much as possible online brainstorming meetings because it's difficult to focus for more than 30 minutes on a call. We've implemented the culture of open ideas. Everyone can contribute to the project decisions.

The culture of open ideas in remote teams is achieved by creating docs, writing down the ideas in Confluence, preparing proofs of concepts and presenting the outcome of it in Confluence again.

Another way of communicating ideas is done through the Slack app. If someone has a loose idea in one's mind, then such a developer can communicate it on a division slack channel. If the idea gets some interest we encourage to write the docs, so we can analyze it in our own pace and in the time we find the most profitable for us.

This is really important. Everyone has different styles of work, everyone has different moments in a day, that they work the most effectively. Putting ideas in docs and making a habit of reading the docs and involving in discussions is crucial for our success.

Onboarding docs for newcomers

I bet you had that feeling in your career. You're joining a new project, new team, you've landed a new job. You got introduced into a project, but still you have no idea on how to start coding and contribute to a codebase. Probably, you kept asking your new team mates about how to do something, why is that done a given way, etc.

Don't have to answer the same questions all the time

Having the docs pays off by not wasting developer's time on answering the same question over and over again, that comes from the new team members. So the experienced developers will focus on things that matters in order to make project or business going successful without distractions in the development phase.

Decisions revision

Anytime when some new team member has an idea, one can check the docs, check the decisions team made in the past. Even the feature analysis can be re-read and updated according to the new situation. If there's a new, better solution then it might be worth to discuss it and make some action points, for instance doing a spike, a proof of concept, etc.

Project coding practices

Additionally, documenting the coding best practices the team incorporated eases introduction of new developers to a project. They will have less stressful first pull request/merge requests in the project, with a high chance of not having much comments regarding the code styling. In most cases it will be solved by automated tools as well, like ESLint or Prettier on the frontend side.

It requires team members engagement

Saying that writing the documentation is important, is very easy. But such expectations has to be a goal of everyone in the team. If fellow developers doesn't want to contribute to such documentation, then the idea is useless. It requires effort, but it pays off in the long-term.

The process

having an idea
creating RFC
waiting for comments
making decision
creating ADR
implementing the idea

RFC

What is RFC? Maybe some of you have heard that term before. It’s basically a request for comments. It’s a document where you can:

have a discussion before implementation,
get to know what others think about an idea,
ask for help in particular challenges.

It should:

be non-decisive,
be stored in a specific, known by all, place,
have author, due date, title, status and description. So it’s easy to determine who made the document a what is it about and what is its status.

How to make a good RFC?

Writing a good RFC document should include:

clean structure,
contains meta description,
clearly defines a problem/challenge,
provides at least one possible to solution, analysis, research take-aways,

Having all of them placed in the document, definitely helps to understand the challenge and it help other developers to give some insights on possible solutions that has not been discussed yet.

Sample RFC

Having strict deadlines helps making decisions faster. I found it very common, when no strict due date was set, then the idea got blurred within the time and it was not implemented at the end.

Furthermore, setting up a strict deadline helps other developers (the ones interested in the topic) to focus on the topic and to not put it away to get back to it someday in the future. If a developer didn't take part in a discussion in a particular RFC, then such person's voice becomes unheard and not important.

At the end usually, it's not up to a RFC author to make a final decision. It's a team effort in most cases. Only some minor architectural decisions can be taken by a single developer. Like setting up some ESLint rules for code linter.

Should I put a comment in every RFC?

No, if you're interested in the topic explained in the RFC, but you have no meaningful comment to add, you can always click on the Like button (if it exists). It means, you've read the doc and you like it.

If you don't do anything then it means that you don't care. Of course, there's no need to take any action in all open RFC documents. You can focus on the ones that you care the most.

Strict deadlines

Having strict deadlines helps making decisions faster. I found it very common, when no strict due date was set, then the idea got blurred within the time and it was not implemented at the end.

ADL

ADL - the architectural decision log is a collection of architecture decision records. It's the final destination where all the decision logs should be stored. Anything outside of it is not a final decision and should not be followed by any developer.

ADR

The ADR is a document containing a problem context and a description of consequences of a particular decision that was applied in order to solve some specific challenge. This is a final decision record. Every developer should follow that with no doubt and questions.

Goals of ADRs

ADR document should be based on RFC document explaining the problem and possible solutions. Having good ADR:

reduces a big amount of tribal knowledge,
strengthen the tooling around ADRs, in support of Agile practices as well as iterative and incremental engineering processes,
builds a written-down history of a project development and a decision making process. Project history awareness makes the future development better.
registers some tough decisions made upon RFC comments and discussionsm
concise list of project decisions with explanations that is easier to read for project.management.

How to make a good ADR?

A good ADR is consist of:

clean meta description (author, decision status, decision date, decision excerpt, link to a RFC),
in short defines a problem,
in short describes a final decision.

A tip from my end, if you want to keep ADRs in Confluence, then I suggest using tagging/labeling in order to make a nice appearance of decisions in the summary page.

Sample ADR

Here you can see some sample ADR document. It’s kind of similar to RFC in the structure but it has some differences as well.

There’s meta section. Then below it we put short description of a challenge we solved and the final decision section.

Summary

Creating good project documentation is not an easy task. It requires a lot of effort, discipline and engagement of whole team at the beginning. Fortunately, at the end it pays off with reduced amount of meetings, having the whole project knowledge documented in one place, so everyone is able to get it and read, instead of constantly asking questions.

It's really rewarding in the long term. You don't spend time on explaining the same stuff.

I suggest to follow the points below, if you want to have a succesful project that can be maintained for a long time and it doesn't require much effort to understand technological choices and business decisions:

Avoid tribal knowledge,
Make communication async,
Reward creating docs,
Maintain docs!