Back

Onboarding

Software Development Knowledge Sharing Methods are Broken: Here’s Why

The level of knowledge sharing in software development teams can make or break a team. Getting tribal knowledge across teams is critical for onboarding, training and situational development challenges. Yet, most companies are struggling with knowledge sharing as a result of lack of knowledge management.

The common knowledge management methods engineering teams are implementing today may pose some challenges. Stay tuned, in the end I will cover requirements I believe are needed for a truly successful knowledge sharing method.

...
Method #1: Backlog tasks

Many organizations introduce new code and projects to developers by giving them an assignment from the backlog, pushing them in to figure it out. The expectation is that by dealing with the task, the developer has to learn the methods and best practices of the project and code. When companies use this method, they usually try to assign tasks that are rather simple, and let the new hires learn by tackling them by themselves.

Challenges: While this method might be an easy solution for companies, it is not the best way to share knowledge. It is extremely hard for engineers to assess what a task may involve, and many times the new team member will get to a task that he or she has no real way of solving without asking many questions about.  This could also be a very frustrating and demoralizing experience.

In addition, with this approach, it may take months for team members to get a hold of all the important parts of their team’s code. Too often, the first tasks one gets will reflect on future tasks, so they are often within the very same area of the code.

Method #2: Practice Sets

Not as common as handing-off a task from the backlog, yet more and more organizations are creating  “practice” sets. Some companies implement this method when onboarding new developers, so that all new hires are given the same task. This way, many existing developers can assist them because they also were given the same task when they joined the company. If the task is well structured, it ensures that new team members touch upon different parts of the system their team is responsible for.

Challenges: Creating a good practice assignment takes time and effort. Harder still, after a short while, this assignment becomes outdated and requires maintenance. In most companies, this means the practice assignments become ineffective, and are therefore thrown aside after a while.

Method #3: Checklist source

Another popular method is to provide developers with a document  or a spreadsheet with a list of resources for them to learn from.

Challenges: While this is a good knowledge source, it is not a good knowledge sharing solution. Reading, understanding and identifying the relevant information from such a doc requires guidance. But more importantly, these docs tend to become irrelevant very quickly. As a result, the level of trust in the documentation lowers, and the developer will no longer count on it to provide valuable and helpful information.

It is worth noting, however, that a checklist document can be very valuable for knowledge management of processes like how to set up a new environment, or a list of tests to run on a day of a version release.

Method #4: 1:1 Sessions

Instead of trusting documentation, many companies assign an experienced team member to explain the code and projects in one-on-one sessions with developers. This is also the case when an experienced team member needs to get into parts of the code she or he hasn’t contributed to before, even though they may know other code parts really well.

Challenges: This is a high-quality solution that ensures deep understanding. However, it is not scalable or repeatable. It also highly depends on the mentor or the most knowledgeable member on the team - not all engineers, even the very talented ones, have good teaching skills.

Method #5: Project Management Tools

Companies implement different knowledge management and documentation tools for sharing information, documents and enabling developers to ask questions. Some tools provide a centralized place to share documents, like Google Drive, One Drive, SharePoint, and even Wikipedia. Others focus on project management, like ClickUp, Jira, monday.com, Trello and Asana.

Challenges: These tools are helpful as knowledge sources, and many of them have cool features like “search” and external integrations. However, the information they contain is usually high-level or task-related, and not code or context-specific, as it is detached from the code. Using such tools means that with changes made to the code, the information stored in these resources quickly becomes obsolete.

In addition, it can be very difficult to find and extract the relevant information from a sea of data. That is, being able to find the relevant information - right when you need it, when it's spread across a bunch of documents.

Method #6: Pull Requests

A common notion in the development world is that good code doesn’t need documentation. If context is needed, the Pull Request will tell the story of adding a feature or fixing a specific bug.

Companies can then send developers to read a specific Pull Request to understand a part of the codebase.

Challenges: Even great code explains only itself, not the entire flow, which is required for being able to really get the full picture. It is clear that the process of really understanding code includes… well, reading code. Pull Requests can help, but if the list of relevant Pull Requests is not constantly updated, it will only explain a snapshot in time, and might not be relevant when a new developer reads them. After all, code is updated very quickly. In addition, not everything can be contained in the codebase. In case of multi-repositories, it's very hard to follow a Pull Request that actually depends on Pull Requests from other repositories.

Method #7: A Champion

One of the most common knowledge management recommendations is to instate a champion. This person documents, reminds everyone to document, and perhaps even sets up knowledge management sessions. Often, this person rises to the occasion when she or he is frustrated with the state of knowledge sharing in the organization, and then creates documentation and processes.

Challenges: The lack of sufficient industry tools for knowledge sharing and developers not seeing the value of knowledge management makes this role a very frustrating one, and often inefficient. Knowledge sharing is a culture, not a project. In addition, placing the burden of the knowledge management of an entire organization on one person’s shoulders is unscalable and will probably lead to deficiencies in the process due to human error and lack of resources. This is especially true if the role is a side-gig to the main development role, as it often is.

Method #8: Learn as you go

Ultimately, what ends up happening is that developers learn as they go. They ask questions over Slack, Zoom or face to face, look at Confluence or commits, and try to figure out if the documentation is up-to-date.

Challenges: This is not a knowledge sharing solution. It is a compromise on the existing lack of knowledge management tools and methods. Engineering teams pay the price for this deficit in productivity and creativity, and with growing frustration.

Continuous Documentation vs Kicking the Can Down the Road

The challenges each method poses cause onboarding and training processes, as well as knowledge sharing in general, to rely on incomplete and outdated information. When documentation creation work is piled up, it’s going to be rushed, decreasing accuracy and completeness.

Continuous documentation is a method we foster at Swimm that can enable teams to implement documentation in small incremental steps as apposed to kicking the can down the road. That's because Onboarding, outdated documents, or project switching should never slow a project down.

To keep the process continuous, we need tools or a tool that helps:

  1. Write focused content including tutorials, walkthroughs, and documentation.
  2. Update the documentation as the code changes, to make sure it is always up-to-date.
  3. Share information easily.
  4. Map and identify what needs documenting, to highlight these areas for developers to document, or document them automatically.

Automating and streamlining this process will help engineering teams focus on coding and developing, instead of chasing bits and pieces of information that are situated in different resources, databases, and people’s minds. Thus, we can enable real and efficient knowledge sharing.

***

Welcoming early users to sign-up and take Swimm for a spin: Get access.