Where parallels cross

Interesting bits of life

Do you want to see how knowledge is distributed in your repository? Use code-compass c/show-knowledge-graph to see an interactive knowledge map!

The problem

It is nice to know who to ask for help. One thing that is worth learning in life is to ask. A lot of us come to dislike asking because expresses needing something and makes us look vulnerable. Even if that were true, vulnerability has got a lot of good traits: for once it sets strong foundations for human relations like friendship 1. When I am working, asking is fundamental. It is efficient because you may save time in solving a problem if somebody experienced it before AND, more importantly, you get in touch with somebody! The more people you know at work the better.

So which people should you chat with if you are working on a certain part of the repository? And if you have a problem in understanding the whole repository (and do not wish to go through your Git logs manually to find a contributor)? Could we visualize if there is a major contributor for this repository who can help us?

It is a problem indeed

Apart of knowing who to ask for help, there is another interesting use case for having a view of how knowledge is spread in the code base. It may happen during your career to be working on a project and suddenly discovering that the main contributor has decided to move on in a few weeks. You congratulate them, give them your best wishes, and then in a moment of quiet you realize: "Wait, if they go I am the next main contributor!!!". This is the part where you shiver because you know you miss some project knowledge but it is unclear what exactly. This is something that happened to me, and it is such a basic error to let your pal leave without asking the right questions! It always happen that you discover what you needed to ask just the day after they have left!

What if instead we had hints of what knowledge we would miss if they left?

And there is a solution

Naturally code-compass can help you with that! Let's see how code-compass's knowledge is distributed at the moment:

I am enthusiastic to see somebody other than me popping up in the knowledge map for code-compass! Indeed, recently Blank Spruce has contributed to the project by moving out HTML, CSS, JavaScript and Python code that I had embedded in the main Elisp file. Much cleaner!

You can see in the image that there is a legend on the right that you can scroll. The black big dot is a file (README.org) that cloc cannot recognize as a source file and so the graph leaves it marked as unknown. You can see from the knowledge map that I have copied @Blank Spruce for the latest analyses, and if you cannot see it clearly let me show you:

Another detail you may pick up now is that, if you move your pointer over the name of the module, the text changes to indicate who is the main contributor of that file 2. Once you associate the color to the person, you can easily see how the knowledge is distributed.

Let's look at another code base to get a better idea of how to use this for a bigger project:

This is the knowledge map for xmonad. Who do you think is the maintainer of this project? Naturally, Adam Vogt! You can see it at once from how orange is the repository. So that would be the best person to ask for help if you have a conceptual question about the project. And if Adam plans to leave the project at any point, well... you may need more than the notice period to ask enough questions!

A note: the colors available by default are limited because the projects I work on usually have a decent amount of contributors, but not too many. You can change that though if you need more or just do not like my choice. For that you can provide a list of colors in c/authors-colors (I got some of them from here because a Python script was handling them).

Conclusion

So, curious who to ask for help? Grab code-compass and you are a c/show-knowledge-graph away from seeing how the knowledge is distributed and who to ask help to.