Creating Connected Remote Teams

Piotr Nalepa at UXDX Community: Europe East. Video: https://youtu.be/-0QDn2KJDmg

Readable transcript: edited from the recording's captions for readability (fillers and false starts removed, punctuation and section headings added). Wording is the speaker's own. Timestamps are positions in the video. Names marked [?] could not be verified against the audio.

A story that starts with failure

[00:00:00] Hello everyone. I'm here to talk about creating connected remote teams, because building a good team of developers is very hard, but building a good team of developers that like to share knowledge and write good product documentation is even harder. In the world of COVID, where many companies were left with no choice but to let employees work remotely from day to day, all of them had to find a solution for how to share product knowledge between team members and between teams. Let's talk a bit about my background, what challenges we are trying to solve and how we work in our team.

[00:00:40] Currently, together with my team, we are responsible for migrating the legacy code base to a new tech stack. The new tech stack is based on React and TypeScript [?] and extensive testing on the front-end side, while the back end is based on serverless architecture and GraphQL data providers, with the help of the legacy code base too. The back end of these projects is too huge to migrate very quickly, and yet it's not very well documented, as well as the front-end parts, so we're moving piece after piece.

[00:01:08] I'm speaking to you at the UXDX Community conference because I want to share my story with you. This story starts like the other stories, but it ends somewhat differently. It has a happy ending. The story is about failure. It all began a long time ago. A few years back, there was a decision made to reboot the project code base following some new approaches. It was all going well until it stopped going well. The project was growing, new people were joining teams, and nobody took care of documenting decisions and approaches.

[00:01:47] That led the project to a situation where each team was introducing their own approaches to developing features and maintaining them. In the short term that would not even be that bad, but people started leaving teams and joining other projects, and there was no documentation. In the end, maintaining the project was like fighting a hydra. You fixed one bug, but new ones were introduced, because some potentially unrelated feature was broken. And it happened at least twice, until my team took responsibility for setting up standards. Then everything started looking better and better.

[00:02:26] Who am I? My name is Piotr Nalepa. I've been developing web apps and helping other developers grow since 2009. Now I'm working for OLX Group in the real estate department. We are building web apps for Otodom.pl, Imovirtual.com and Storia.ro. Our role is to build a solid technical foundation for becoming a lighthouse in the real estate markets. In my free time I'm sharing knowledge on my personal blog, where you can find a lot of articles regarding web development.

Tribal knowledge and what can go wrong

[00:03:05] Some of you might already have heard about it. Tribal knowledge is knowledge spread vocally. There is no written document. You have to remember everything, or you might fail because you forgot an important piece of that knowledge, or the whole of it 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 the technologies we have. Spreading knowledge, learning from it, understanding the processes of the past is something that we should make use of from day one when starting any project. It's for the safety of you, me, your company, your work or your own business.

[00:03:53] What can go wrong, because everything is right now, right? Well, everything can go wrong in the long term, because you just don't know. You just don't know why a given coding approach was chosen, what the purpose of the selected approach was, what else was considered at that time in the past. You know just nothing. Were any options considered? Have you considered using Vue.js or Angular? Why, why not? Thinking about obvious features is easy, but during the app lifecycle there can be features implemented that rely on one another. Without having them written down somewhere, there's no way to make our future selves, or even other people, aware of how big the product is and what the connections are between the different parts that seem to be unrelated.

[00:04:51] When business is not going well, you might also want to check whether somewhere in the app development lifecycle anything bad has been added to the product. Or maybe you just want to make sure that reducing the scope of the server architecture won't break it, and you will avoid losing money. Without proper documentation, devs keep on reinventing the wheel over and over again. In the end, your product teams end up maintaining multiple versions of the same page components, like navs or search forms, or data providers.

Asynchronous communication and a culture of open ideas

[00:05:29] In order to avoid such situations, we have to stop and think: how can we do better? How can we improve communication within the team? For remote teams, clear communication is even more important than for in-house teams. When working remotely, you have no chance to see all the details of a team member's reaction. You have no chance to see how he behaves. Most of the time the communication is based on written sentences.

[00:05:58] And here we get to the point. What we win with is asynchronous communication. We try to avoid online-based [?] meetings as much as possible, because it's difficult to focus for more than 13 minutes on a call. Instead, we've implemented a 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 concept, and presenting the outcome of them in Confluence pages again.

[00:06:34] Another way of communicating ideas is through the Slack app. If a developer has a loose idea and wants to mine it, then such a developer can communicate it on a division Slack channel. If the idea gets some interest, we encourage them to write the docs, so we can analyze it at our own pace, at the time we find most suitable for us. This is really important, because everyone has different styles of work. Everyone has different moments in the day when they work most effectively. Putting ideas in docs, making a habit of reading the docs, and getting involved in discussions are things we see as crucial for our success.

Documenting decisions and onboarding

[00:07:14] The answer to all the issues mentioned earlier in the "what can go wrong" section is to document the decisions you and your team are making in the process of software development. The first non-obvious thing that it improves is onboarding docs for newcomers. I bet you've had that feeling in your career: you're joining a new project, a new team, you've landed a new job, you got introduced to your project, but still you have no idea how to start coding and contribute to the code base. Probably you kept asking your new teammates how to do something, why it is done a given way, etc.

[00:07:55] Having such docs helps you a lot in many ways and reduces the need for any additional meetings. Having the docs pays off by not wasting developers' time on answering the same questions over and over again, the questions that come from new team members. The experienced developers will focus on things that matter, in order to make projects or the business successful without any distractions in the development phase.

[00:08:22] And at a time when some new team member has an idea, they can check the docs and check the decisions made in the past. Even the previous feature analysis can be revisited and updated according to the new situation. If there's a new, better solution, then it might be worth discussing it and making some action points, for instance doing a spike or proof of concept. Additionally, documenting the coding practices and best practices the team incorporated eases the introduction of new developers to a product. They will have faster first contributions to the product, with a high chance of not having many comments regarding the code styling and conventions. In most cases such things will be solved by automated tools like ESLint or Prettier [?] on the front-end side, but it's still documentation.

[00:09:20] In the end, in order to have such a comfortable, trackable situation, we have to remember one thing: it all requires team engagement. Saying that writing documentation is important is very easy, but such expectations have to be a goal of everyone in the team. If fellow developers don't want to contribute to such a documentation process, then the idea is senseless. It requires effort, but it pays off in the long term.

The RFC process

[00:09:50] Let's take a look at the process we are following in our department. At the beginning there's always an idea, or a revision of how to do something. Then we create a document called an RFC. Then we wait for comments from other team members, in order to get the best possible solution for our challenge. After commenting, the author and the team make a decision. After making a decision, we create another document called an ADR, and then we start implementing the idea. This process is very important, because it clarifies the needs of the team and brings some standards to defining new processes, new ideas, new solutions, new approaches to coding, and how to keep the knowledge in the team.

[00:10:56] What is an RFC? Maybe some of you have heard that term before. It's a request for comments. It's a document where you can have a discussion before implementation. You can get to know what others think about an idea. You can ask for help with particular challenges. This document should be non-decisive [?]. It should be stored in a specific, known [?] place, so everyone knows where to look for the information. This document should have an author, due date, title, status and description, so it's easy to determine who made the document, what it is about and what its status is. It can be approved, rejected, on hold, in progress, any status that your team decides to use.

[00:11:46] Let's talk about how to make a good RFC document. A good RFC document has a clean structure. It's very important to make the document very predictable and to follow the same structure in all the documents. Each document should contain a proper meta description. Like I mentioned earlier, it should contain the author, the title, the status, the due date, and it should give basic information about what it is about. The document should also clearly define a problem, so everyone can understand where the dragons are.

[00:12:31] An RFC provides at least one possible solution, and analysis or research takeaways. It's important to let other team members know that the RFC author has made some investigation and is looking for other options, is looking for comments, or for making the final decision. On the slide you can see a sample RFC document I created some time ago. It consists of a meta section, a table of contents, a background description section where the challenge is described, possible solutions, explanations, conclusions, and optionally some things to think about in the future if the idea gets approved. Of course, not everything I mentioned here is visible on this slide, but I just wanted to show you that there is a meta description section and a table of contents containing links to each section I have described.

[00:13:36] There's also one thing to mention. You might be wondering, should I put a comment on every RFC? I think no. If you are interested in the topic explained in the RFC but you have no meaningful comment to add, you can always click the like button, if it exists. It means you have read the docs and you like it. If you don't do anything, then it means that you don't care.

[00:13:59] Having strict deadlines helped us make decisions faster. I found it very common that when no strict due date was set, the idea got blurred over time and was not implemented in the end. Furthermore, setting up a strict deadline helps other developers, the ones interested in the topic, to focus on the topic and not put it away to get back to it someday in the future. If a developer didn't take part in the discussion on a particular RFC, then that person's voice goes unheard and is not so important. In the end, it's usually not up to the RFC author to make the final decision. It's a team effort in most cases, and only some minor architectural decisions can be taken by a single developer, like setting up some usb intervals for call clinton [?].

The ADR log

[00:14:53] Another document that is worth mentioning is the ADR, and the ADL [?], the architectural decision log, which is a collection of architecture decisions. It defines a 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. The ADL [?] is a concise list of project decisions with explanations that is easier for project management to reach. The business has to have an opportunity to understand why developers took some decisions when building the app.

[00:15:36] The ADR is a document containing a problem context and a description of the consequences of a particular decision that was applied in order to solve some specific challenge in the project. This is the final decision we covered. Every developer should follow it with no doubts and questions, because the time for questions and doubts was in the RFC comment sections. ADRs reduce a big amount of tribal knowledge, because we have a list of final decisions and everyone has agreed to follow them. ADRs strengthen the tooling around them in support of agile practices, as well as iterative and incremental engineering processes.

[00:16:24] Such documents build a written-down history of a project's development, and it is another decision-making process. Project history awareness makes future development better. ADRs register the tough decisions made on RFC comments and discussions.

[00:16:43] How do you make a good ADR? In general, the ADR document structure is very similar to the RFC. It contains a clean meta description with author, decision status, decision date, decision excerpt and a link to the RFC document. The problem should be defined briefly. There's no need to duplicate the whole problem description from the RFC. You can just refer to it in the description. The final decision is briefly described in the document. You see, in our team the decisions are put in the RFC, and in the ADRs we give a short description of the final decision.

[00:17:28] Just one tip from my end: if you want to keep ideas in Confluence, then I suggest using labels, in order to make a nice appearance of decisions on the summary page. Without this, looking for ideas will be a bit stubborn. On this slide you can see a sample ADR document. It's similar to an RFC in structure, but there are some differences. There's the meta section, then below it we put a short description of the challenge we solved and the final decision, so everyone is aware of what the decision was, what the outcome is, what the problem we solved was, and that everyone agreed to follow it.

Summary

[00:18:18] To summarize my speech today, I suggest: avoid tribal knowledge. Make communication asynchronous. Reward creating new docs. Show other developers how they can make a perfect vomit [?], so that they can reduce the amount of meetings and then focus on things that matter. And finally, maintain the docs. Usually newcomers are great docs maintainers, because they can easily spot outdated pieces of documentation. Thank you.