Knowledge Sharing in Dev Teams — a Problem that Needs Fixing
I’ve had eight jobs in seven years. Eight companies. Eight code bases. Eight different ways of doing things. I’ve been onboarded eight times and I’ve made eight sets of notes on how to access databases, where to find production logs, how to set up test environments and how to update Jira tickets in line with each company’s always unique way-of-doing-things.
There was the “Setting up Biztalk” document — a 24–27 page monstrosity whose page count depended on which dev’s copy I was reading. There was the never ending OneNote file I was emailed to help me set up my dev environment, a process that was expected to take me a week. It took a week.
There were the incomplete Confluence pages, the SharePoint documents last updated two years earlier, the SQL template file that another dev emailed me after I ran my first script on production (the wrong way), and on and on and on.
All these companies were the same in only two respects. The first was that their documentation processes, procedures and ways of doing things were unique to them. There was no best practice, no industry standard, no commonalities between companies. They were all special in their own way.
The second was that there was no easily accessible knowledge base, nowhere to go to for the definitive 12 step setup guide, the deployment procedure guide, the QA and unit testing guide, the giant “This is how we do things here in our own unique way” guide.
They all had HR manuals and employee handbooks that talked about holidays and egregious violations and mission statements. But there was no dev manual, no handbook to help a developer do his job.
In each company knowledge was shared piecemeal. One developer might have a word document with steps to follow to set up her working environment but it would be incomplete or out of date. Another developer would have a copy of the same document, but with additional or missing steps (sometimes both). The dev SharePoint folder would have a different copy still, often twelve months out of date and only editable by a manager.
One dev’s database would differ from another dev’s, and both would differ from the schema on production which would differ yet again from staging.
Each company and each developer, consistent in their inconsistency.
In many jobs setting up your local environment was considered a rite of passage. Everyone that came before you had to do it, so you should suffer in the same way. Ditto the dreaded Biztalk installation, with its 24–27 page document (that’s a post all of its own).
I once worked on a team with ten experienced .NET developers, all contractors brought in to build a new platform for a multi-national company. Each dev started at different times over a two month ramp up period, and each wasted their first week getting themselves up and running. Ten weeks of senior developer time, flushed down the drain because there was no common repository of basic “How to” knowledge.
And that’s just the start.
After the setup process, when you’re up and running, you’re still chasing knowledge. Knowledge that every other dev on the team already has to one degree or another but that is shared in a haphazard fashion at best.
Commonly used database queries are never shared. You have to look through code, work out the relationship between objects and how they map to database entities, all before you can run a query joining three or four tables to extract some basic info. Yes, you learn a lot about the codebase and the database by doing this, but an experienced developer would have learned just as much by being pointed to a SQL file in a shared repository with a few common queries for each different area of the database.
These are queries that every developer on the team has already built up themselves in their own private knowledge bases. For some, a series of Word documents; for others a OneNote file, a private Trello account (probably against company rules), an online wiki or a folder of text files. Every developer has this somewhere. No developer ever shares unless the new guy asks him how to find X in the database, and even then the sharing is never a SQL file common to the team, it’s a query copied into an email or to a private chat in Teams or Slack.
What to do in the event of an emergency? Never shared. If a web service goes down, one or two devs on the team might know how to restart it and what that restart entails. But if those devs are out of the office, whoever remains is left guessing, browsing though the list of production and staging apps on Azure or AWS, hoping against hope that a simple restart will fix the problem.
No shared knowledge. No team knowledge. A collection of private knowledge repositories shared bit by bit in an unstructured fashion.
This is the state of play in so many dev teams. Corporate, startup, somewhere in between, it doesn’t matter. All the same. Teams of devs duplicating the work of other devs, sharing nothing. Rediscovering every wheel.
When a guy leaves, what happens to his local repository of queries, of how-tos, of processes for deploying to staging and accessing production? He deletes it. His final act before he departs after many years. This is not a malicious act, though the destruction of all that data and knowledge might look that way from the outside. He deletes it because it’s his and his alone. It’s not shared, never has been. His resource, not the team’s.
If he went to the Development Manager before hitting the delete button and asked if anyone wanted his notes he would be met with a scratched head and confusion: “Notes, what notes?” The dev manager would shake his head at the crazy-knowledge-base-guy and then go back to his work, updating his personal OneNote file with the latest missing step in whatever he was working on.
In most of those eight companies over those seven years, Confluence was the tool of choice for sharing information. It’s the market leader, but developers rarely use it. Now and then we’ll be instructed to document a complex piece of work for posterity, but there will rarely be any consistency to that documentation and it tends to fall out of date after one or two release cycles.
Sharing knowledge across a development team is broken. The lack of a robust knowledge base costs the team every time a new dev starts work, every time an app goes down on production when the guy who built it is on holiday, every time a developer spends an hour putting together a complex SQL query that the guy sitting across from him already wrote three months earlier.
It’s broken because the tools that should be helping with this are broken. There are no such tools specific to development teams. We’re all being instructed to use common company wide tools and processes such as Confluence, SharePoint or Datto folders of Word documents, or worse still, nothing at all.
Developers don’t hoard knowledge because they want to keep it to themselves, they do so because there’s no easy, quick and structured way to share that knowledge with their team.
This is a problem that needs fixing.
Originally published at http://darrendevitt.com on February 10, 2020.
