Software development is often as much about technical solutions, as about understanding the business and the context which lives outside of the codebase. While we have a lot of tools for inspecting the code and managing its lifecycle, most of the developers do not have even a single tool that would be doing the same for the knowledge.
Various documentation systems try to fill that gap but fail miserably in most of the cases. Code tends to change much faster than documentation, and linking specific parts of the documentation to a specific part of the code is hard. Maintaining it is close to impossible.
Surely we can do better.
That is why we created CodeTale. A project is running by Rafał Mucha, Jakub Bania, Wojciech Mazur, and Piotr Kukiełka, who is a main originator of this solution.
We knew exactly what we wanted
- Reuse of the existing knowledge sources. There is a lot of locked potential in existing data but usually, it’s prohibitive hard to extract it. We need to make it much more accessible and useable.
- Documentation which can be linked directly to the code and viewed together with it. At the same time, we do not want it to live in the code repository – it should be out of our way when we do not need it.
- Making information sharing simple & easy. Nowadays with a lot of teams being collocated or partially remote, knowledge tends to be distributed between many different team members and we need a way to glue it back together.
How to address those problems in practice?
Tap into existing knowledge sources
Different companies and teams are using various tools for collaboration and knowledge sharing. But is there any common one between them, a source which would be always available and, at the same time, is information-rich? Turns out there is: source control management system. Nowadays the majority of the teams are using some form of pull request workflow for ensuring proper code review and code quality. From those reviews, we can extract many useful comments and discussions which gives us great insight and additional context for the code. We just need to process them and find a way to make them much easier to explore.
Documentation living with the code
If we want documentation to be very accessible for every developer, we should provide it as part of the environment they are working in. In most cases that means some kind of editor or IDE. We know different people have different preferences and requirements, so CodeTale is going to support multiple tools. Currently, that means Visual Studio Code and the whole family of IntelliJ based products, but we are not going to limit ourselves to that.
In those IDEs we provide a very easy way to find and explore comments and discussions relevant to the viewed code. Thanks to that developer is always aware of past problems and considerations connected to the code in question. Furthermore, the system which is implemented is intelligently linking comments and discussions with the existing code regardless of new commits, branch changes, or changes in the code. Because of that developer does not have to manually track changes through history, but is always able to immediately find the relevant part of the information.
Share the knowledge
Exploring potential locked in all the code reviews is great, but sometimes new problems and questions arise which might have not been addressed yet. In such situations, we want to give developers an option to ask new questions and commenting on existing code with valuable insights. CodeTale will automatically suggest people who are probably best suited to answer the question, and notify them about the question which might concern them. To view and answer it they won’t need to leave their IDE, so they can use all the benefits IDE gives them (like code navigation or history preview) to fully understand the question and answer it in the best possible way.
Furthermore, discussions like that, regarding general issues, could be later explored by other developers, so that knowledge is not lost and does not have to be rediscovered later. To make that process even easier we have added options for tagging the comments, which will allow everyone to search only in topics and categories interesting to them.
Plans for the future
Code Tale is still under development but this work is at a very advanced level. We started initial tests with a group of selected users using the VS Code, and since we are just finishing polishing IntelliJ plugin we plan to extend our testers group pretty soon. We plan to add support for live discussions and bring our plugins to the markets. We also want to provide add-ins for GitHub/GitLab so no external tool will be needed for data syncing.
Research & Development at VirtusLab
R&D’s idea is rooted in our culture, it plays an integral role in VirtusLab’s innovative product development. We can proudly admit that our R&D process is not just a selling point, but a thriving initiative – thanks to it, a project like CodeTale can be developed. Our employee’s research is improving the daily work of our #VLteam, the services we are offering to our clients, and contribute to the tech community.