DEV Community

Cover image for Sharing knowledge with the principles of open source
Sune Monrad for IT Minds

Posted on

Sharing knowledge with the principles of open source

Why is it so hard?

Knowledge sharing is arguably one of the hardest disciplines in organizations with multiple development teams. More often than not you’ll find that one team is setting up things like libraries for logging, CI/CD toolchains, and a lot of other tools and software. A lot of boilerplate code is being produced and we find ourselves doing it over and over again when starting new projects. With a growing code base, a team might choose to isolate the shared components and bundle them as NuGet packages, maven packages, npm packages, or other kinds of packages used in the tech stack.

Creating almost the same code over and over again feels a bit like re-inventing the wheel over and over again even though you know that the wheel has been invented many times by other teams.

So why don’t we just share the knowledge and use the code produced by others to save time? Well, it might sound easy - but in fact, this task has turned out to be more difficult than what you’ll think at first.

Let’s dive into some of the things that seem to make knowledge or code sharing so hard.

Who is working with this?

The first problem I’ve encountered when trying to not re-invent the wheel has been to localize other teams who might have solved the problem. In larger companies with multiple development teams, you’ll most likely find a team that has dealt with an issue similar to what you are trying to solve. The main problem is that, unless you already know the right person, then it’s often very difficult to find the person, that might be able to help you, and most often it is faster to just write the code yourself.

It’s not quite my use case

Ok, let’s assume that you’ve managed to localize the right team and even the right person - perfect! Well, so it seems until you realize that the use case is not quite the same as yours. Some tweaks are needed to make it work - bummer. To solve the issue we might end up just copying the code and making some slight modifications to make it work for our use case. Also, this is often the case if the piece of code was buried within another project. Even though this might solve the problem here and now it also comes with its own set of complications. Copies tend to drift apart as different people maintain the code base leading to multiple teams solving the same problems or that bug fixes to the original code are incompatible with the code you modified.

How do we fix it

My guess is that if you are a developer, chances are you’ve been using a fair share of open source code in your work. As developers, we use a lot of packages rapidly speeding up the development process. If the code doesn’t fit or if we find a bug we can either report the issue, request a feature, or even improve the code ourselves and let the code owners decide if the code should be mainlined with the existing codebase. We are able to share code even though we work on many different projects commercial or open source and even though we might be situated in completely different countries.

So why is this global knowledge-sharing working so well? To me, the key things to take from this are discipline, ownership, the right tools, and structure as well as great communication.

Let me explain...

Applying open source on closed codebases

First of all, let’s address the first issue I encountered: not being able to localize the right team. In open source, we’ll most often than not turn to our favorite package marketplace like nuget.org or Maven Central. We’ll look for packages that solve our problem or we might take a look at the code at GitHub. We might have found the code on Stack Overflow after a Google Search or after asking for help on the platform.

Now, let’s try to see if we can apply this workflow to an organization instead.

All packages in one place

You might already have the software needed to do this. If you are working with C# code chances are high, that your existing CI/CD platform has a build-in feed for NuGet packages that can be used for storing company packages. Even though this is a great start, I’ll recommend a platform that can hold different types of repositories so that you’ll be able to share code no matter the tech stack you are using. Artifactory is a tool that solves this problem, but there are plenty of other solutions that be might be just as good. The main thing is that it should be easy to discover useful packages.

Ask for help

An email to all developers doesn’t seem like a good idea unless you really want to be unpopular in the company. Instead, we need a place where we can ask for help - like Stack Overflow. Even though Stack Overflow provides a solution for companies we don’t really need it to get started. Having a knowledge sharing channel on your Slack account or a team on Microsoft Teams will get you a long way. Just as long as it is possible to share knowledge without bothering everyone at the same time. You might even want to create a Knowledge Sharing team with different channels for different technologies to be able to further filter out relevant content.

What about the code itself?

There is no doubt that GitHub has played a big role in the success of open source code, and there are plenty of things that we can learn from the open source communities when it comes to collaboration. Let me highlight some of the things that I’ve benefited the most from.

One repository per package

This might be up for discussion but I find single repos to be a bit clumsy for what we are trying to achieve. Instead, I prefer to have a lot of smaller repos with a very distinct purpose. This way it is much easier for other teams to benefit from the code and contribute to the development.

Speaking of contributions let’s talk about just that...

Git and Pull request

Most open source projects use Git as a source control solution. Even though other solutions might work as well we have one main benefit from using Git that will make collaboration between teams a lot easier.

Pull request and strict access control makes it very easy to ensure that the code is kept tidy and aligned with the rest of the codebase. Also, you might benefit from having rules ensuring proper code reviews, CI/CD workflows, and testing levels.

This leads me to the third benefit:

Having a code owner

Having one or two people responsible for the source code ensures that there is always someone who will make sure, that the code works as expected as well as new features are aligned with the purpose of the source code. Those people should also be the ones reviewing the source code as they will know the code base and different use cases the best.

Take the time to make it accessible

To really benefit from this approach the code needs to be accessible to others. Make sure the code is well structured and that the interfaces are well documented. Also, be sure to include a readme.md explaining the purpose of this particular project, how it is used, and how to contribute to the development. This will definitely increase the chances of other developers being able to utilize the code.

In conclusion

The open source community might seem like a very chaotic place as everyone is able to create code and share it with the world. And even though this is true, we might learn a lot from how development is done on most open source projects. If we start treating our closed source code as open source and use the right tools in combination with good discipline, code owners, and we take the time to document the interfaces and the purpose of the different projects, we’ll be able to save a lot of time on re-inventing the wheel over and over again.

Discussion (1)

Collapse
artydev profile image
artydev

Interesting thank you.
But remember that from chaos, beautiful things can arise :-)
Regards