Knowledge Base

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.


To hear more from me, you can follow me on Twitter or on LinkedIn.

Solo Developer

5 Reasons Your Side Project Never Became a Product

Do you have side projects sitting idle in folders or git repositories, untouched for months or years? How many are 80% complete? Functional and occasionally used by you but not in a fit state to sell or to give away? How many seemed like great ideas at the time?

The sorry state of the side project is the bane of every hacker’s life. We have an idea. We get stuck in after work or at the weekend, all eager and filled with passion. Weeks or even months pass, progress is made and then we stop or we move on.

Sound familiar?

I’ve worked on a dozen side projects that I’ve polished and released. Some have been commercial desktop products, some free online apps, but all reached a state of completeness that allowed me to release them to real users.

Every time, I’ve had to fight with myself to cross the finish line, to get the project into a state where it’s no longer a project but a product. Crunch time usually hits at the 80% mark when it’s usable by me with a little manual configuration. The UI might be a bit embarrassing, important things might be missing, it may be a long way from being release ready.

It’s at this point that my inner demons (and yours) do their damnedest to de-rail the project and prevent it from ever becoming a product.

Here are five reasons your side project stayed a project and never became a product.

1. The boring bits at the end

The early stages of a side project are fun. You and only you get to choose the tech stack — no more libraries that are six years old, no more antiquated IDEs and database clients. It’s new and fresh all the way.

But as the project grows and gets closer and closer to becoming an actual product, the fun gives way to the mundane. It all starts to feel like the day job.

Is the wording right on the menus and buttons? Is everything enabled or disabled when it should be? Have you built the installer, code signed the EXE files? How do you even get hold of a code signing certificate?

It’s a list that never seems to end, filled with annoying little jobs that take all the fun out of building your own app. But they have to be done, otherwise your project stays a project, gathering dust and reminding you every day of your failure.

How do you fix this?

You fix it one task at a time. But first you need to define those tasks, to build a list. Everything goes on the list: the bugs, the cosmetic changes, the missing features, the installer, the website, the user forum, even the code signing certificate.

I know what you’re thinking: “I don’t need Jira for my little side project.” You’re right, you don’t need it for your side project. But you do need it — or something similar — for your product.

As I was building the first version of Atomic Scribbler back in 2017 it was at the 80% stage that I introduced Jira. Atomic worked — for me. But it was nowhere near ready for the wider world.

At 7 AM one weekday morning, sitting in Starbucks on the Quays in Dublin, I built my first Atomic Scribbler Jira list. Everything was on that list — over 100 tasks, bugs and user stories. Some would prove to be a ten-minute job, others would take me days to complete. I listed them all and then I set up my first sprint: seven days, twenty tasks.

That afternoon I was working in another coffee shop and dragged two tasks to the Done list. Each day I repeated the process. One or two tasks in the morning, drag and drop, one or two in the afternoon, rinse and repeat. At the end of that week all 20 tasks were completed and I set up the following week’s sprint.

When you feel the momentum, when you watch as tasks get knocked down each day, the end becomes real. You start to see release day just around the corner. A product, not a project.

2. You lost your focus and drive

We’ve all been there. When passion is not enough, when Netflix or Facebook or shiny new things pull at us, tearing us away from our project. Procrastination can make us lose days, weeks, even months. For many of us it’s the end — we never find our way back to our project and our product dies before it’s even born.

How do you fix this?

There’s an entire industry out there selling answers to this question. Self-help guides whose sole purpose is to help us kill procrastination, motivational speakers who fly into stadiums by helicopter to rescue us from ourselves, not-quite-academic books that talk about Grit and Mindset and Deep Work. All answering the same question in different ways: how we can work better.

I find the most useful approach is to work my side project the way I work the day job. Give myself a boss and do what he tells me to do, just like at work.

What do you do when your boss assigns you a list of small, uninteresting tasks? You grumble, you tap the keyboard aggressively, and then you start work. You keep working, day after day until the list is complete. What do you do when he asks you to write 1,000 words describing some new functionality? You may hate writing, it might not be your thing, but you sit down at 10 AM and you get stuck in regardless.

It’s not the money that makes you do the work, it’s the instruction from a guy you see as being entitled to instruct you.

That final 20% — those tasks that are stopping your project from becoming a product — these are just the sort of tasks you dislike doing in the day job but do nonetheless.

Treat your side project like a job — a couple of hours OT each day. Be the boss. Write up those Jiras and assign them to yourself. Start a weekly sprint and hold yourself as accountable as your boss at work holds you. It won’t be long before that product starts to take shape.

3. It has to be perfect

How often in the day job are you asked to build something quickly, to cut corners, to keep it simple. “It doesn’t have to be perfect, it just has to work. There’s a demo on Tuesday.

Heard this before?

A side project is different. No one can tell us to rush new features, to leave stuff out, to park the unit tests and come back to them later. We’re determined to do everything just right. No shortcuts.

The trouble with seeking perfection is you never get there. Like the writer who keeps revising each paragraph and never types “The End”, you keep finding improvements that just have to be made.

If your app gets a mention in the New York Times you need to be able to scale quickly — better put that in place now, just in case. And what about those French users? They might not be there for version 1, but they’ll be along soon enough — better implement that multi-language support right at the beginning, it’ll save time later. Windows 12 is due out next year — I’ll install the early release candidate and ensure my app is compatible, nip any issues in the bud while the code is fresh in my mind.

This reads like a joke, but it’s not. This kind of perfectionism kills your project before it has a chance to become a product.

How do you fix this?

You need to trim features, not add them. Your version 1 should be the product that is good enough for a tiny proportion of your potential users, not for all of them.

Draw up a list of features and scenarios that you think you have to handle in version 1. Park Jira for now, do this on paper. Write it all down — export options, backups, multi-user support, tags (tags always turn up on these lists), printing, Google and Facebook login, whatever.

Then take out the red pen and go through the list. The question you should ask for each item on that list is: “If I leave this out, can a user still use my product?

That’s it. Not “Will it be perfect?” If one user can use your product without that feature, cross it out. Park it until version 2.

This approach has an advantage beyond helping you get version 1 out the door. Half the items you crossed out will never be mentioned by your early users. It won’t be that they can live without them for now, it will be that they have no interest in them at all.

My red pen list for Atomic Scribbler was huge. I’m on version 6 now and I still haven’t implemented some of the items on that early list — not even the tags. Why? Because a year and a half later with many thousands of users, no one has asked for them.

An imperfect product is still a product, but a project is always just a project.

4. You got bogged down and didn’t know where to go

Like a writer at 30,000 words whose plot has fallen off a cliff, you coded yourself into a wall. Everything was going well, the project was coming together, then you found yourself stuck with no idea where to go next.

You lost your vision for what the project was, or you never had a vision to begin with. You never saw the product.

How can you possibly fix this?

It’s easy to mistake this inability to move forwards for procrastination, but it’s not, it’s worse. Something is wrong with your project. You don’t know where to go next because you haven’t defined your product-to-be or your target user. You’re building something for a generic user when you should be building a product for the smallest niche possible.

With Atomic Scribbler that niche was creative writers writing novels. Not writers in general, not bloggers, not journalists, not poets or academics. Sure, they could all use the app, but it wasn’t for them. A single developer can’t build a generic app filled with features for a multitude of different users.

Once you have this user, look at your product from his perspective. What’s in there that he doesn’t need and what’s not in there that he has to have or he won’t touch version 1? Draw up a plan to tidy up your project, to trim features he doesn’t need and to add the lightest possible features that he must have. Forget about future scaling or delivering version 6 out of the gate. This is version 1 for a specific user.

Build a vision for your product around this one niche user and hold onto that vision.

5. You didn’t move outside your comfort zone

My first two jobs I wrote desktop apps in C++. My first project that turned into a product — PageFour — was a desktop app written in C++. I was a C++ guy who built desktop products.

It was only later as I jumped from company to company as a contractor that I realised how quickly I could pick up new technologies and how valuable that skill was. Different companies, different tech stacks, everywhere different ideas and ways of doing things. Suddenly anything was possible.

Most of us live in a bubble defined by our history and experience. We code in Java or Python, we’re back-end or front-end. We’re tech guys or customer facing. This inability to put on different hats can kill our side projects before they ever become products.

How can you fix this?

You have to step outside the bubble, work in areas that you’re not familiar with or that you think you’re not good at. This means learning new technologies when your project calls for it and stepping into sales and marketing roles as well as writing code. Not a database guy? Start learning. Never built a web service? If your app needs it, you need to learn it. Never talked to customers? Start now.

You need to meet people who populate these other fields, who work and live in the areas you’re weakest. Don’t go to the hacker meetup group, give the marketing group a try. Instead of connecting on LinkedIn with fellow devs in your home city, connect with non-tech start-up founders, with sales and customer centered people, with writers and bloggers.

Take meetings, have lunch. Everyone wants to meet up. Everyone who’s worth the time at least. Talk to them, share ideas, and above all listen and learn.

For your project to become a product it needs more than code. You need to step into other worlds and learn new things. You need to realise that none of these other skills that are required to build a product are any more difficult to learn than the languages and frameworks that you pick up with ease.


To hear more from me, you can follow me on Twitter or on LinkedIn.

Solo Developer

Building an app without quitting the day job — 6am coffee shops and the corporate grind

“If you want something done, ask a busy person.”

Why is it that the guy who tosses in his job to follow a start-up dream fumbles and procrastinates while so many great apps shown on Hacker News are rolled out by someone in full time employment?

Why is it that the starting-out tales of so many great writers tell stories of chiselling out an hour or two here and there, in between jobs and kids, while the creative writing student — who has an abundance of time — never seems to finish that first novel?

Busy people find the time. They know how to use the little time they have to productive effect. Do you want to write a novel? Build an app? Start a business? You can do all of this and keep the day job.

Last year I built a new desktop app called Atomic Scribbler. It was a passion project of mine — a full writing environment for creative writers to replace Microsoft Word and maybe even give Scrivener a run for its money. I built it in Starbucks in the early hours of the morning and in Café Nero after work, spread over the course of a year while working full time contracts in Dublin.

Anyone who’s worked on big corporate projects knows that the pace of development can be glacial, with days assigned to tasks that a good developer could polish off in hours. This slow pace can sap the will and passion from the bright and the eager.

I’d worked in these environments for many years and I knew that the way to survive was to let my creativity and energy flow into other projects. Do the corporate job, but don’t let it define you. Define yourself by what you do before and after the job — make the corporate grind a small part of your day, not the centre of your life.

My day… what it looked like.

I’d rise at 5:30 each morning, take an early tram into Stephen’s Green in the city centre and walk down to Starbucks on the Quays, passing the homeless of Dublin rising from their shop doorways as the delivery trucks arrived.

The mezzanine area of Starbucks was empty at that time of day and would remain so until 8:30am when I left for work. Lap-top out, I’d fire up Jira and start working on the next item on my list, usually a small enough piece of work that could be completed in two hours.

Each day, the same routine. Two hours working in Starbucks then head into the International Financial Services Centre to start work on a Big Data project for a German bank. We were housed in a classic corporate building close to Connolly train station, complete with open plan offices, sci-fi access gates and a single pool table placed in a strategic location so that it could be seen from the street outside.

No one ever used the pool table and everyone wore black shoes. There wasn’t a Metallica T-shirt in the building.

When 5 o’clock rolled around I’d stretch my legs and take a 25 minute walk through the city to Camden Street, stopping at Café Nero where I’d order a mint tea — no caffeine that late in the day, not if I wanted to stick to my daily routine and rise at 5:30 the next morning.

An hour here would see me finish off the work of the morning or start something new. Three hours a day in total, ending at 6:30 — a whole free evening ahead of me to go out with my girl, immerse myself in a good novel, see a film or take long walks up and down the pier at Dun Laoghaire.

Five days a week would see me put in 15 hours on my app — but those were not corporate hours. There were no meetings, no requirements gathering, no liaising with or waiting for other departments. There was no uncertainty — decisions that needed to be made were made and acted upon on the same day.

In 15 hours I achieved more than I would in three weeks at the day job.

Progress…

As the months passed, the app filled out, required features appearing in skeletal form and then popping up fully implemented in the user interface a week later.

Big Data gave way to a web app project at one of Ireland’s leading banks. A new office in the same part of town, interesting for a few months until the project ground to a halt as the many different teams across the company failed to work together.

The Jira list got shorter and shorter and the end was soon in sight. The backlog, which had stretched to hundreds of items, was soon reduced to the final 20 or so that signify a project about to go live: website, license keys, hooking up to a payment collector — all things I’d done before but steps that so many app developers discount.

I paint a picture that looks simple and problem free, but it wasn’t all sailing. Into the mix of long days I tried to fit a social life of sorts — dates with the girlfriend, hill walking in Connemara or Killarney at the weekends, the odd piece of work that the various family businesses required.

And then there was the ugly mug of the lizard brain that kept telling me to stop, to slow down, to take it easy for a while. The closer I got to the finish line the louder my inner demons shouted, doing their damnedest to wreck Atomic Scribbler before it got out the door.

This is the point where so many creative people fall down. They listen to that inner voice and they let it win. They abandon their novel after the first draft or after a single editor expresses displeasure. They stop working on an app that’s 90% complete.

Those final weeks with the finish line in sight are the most dangerous. It’s here that the amateur slips up and starts working on something else — a new project that they thought of only yesterday or a shiny new framework they read about on Hacker News — taking the focus and the passion away from their almost complete app.


And it’s here that the professional powers on through and pushes version 1 out the door, warts and all and to hell with the haters.

As for Atomic Scribbler: it went live, as did versions two, three, four and five over the following months. I’m using it to write this post and it has a community of dedicated followers, growing each week. It fits nicely into my wider portfolio of products for writers.

The work goes on. SmartEdit — a sister app to Atomic Scribbler — is my focus for the coming months. The alarm still rings at 5:30 each morning. There’s a new contract with a new company in a new location. And there’s a new coffee shop — but no mezzanine with a view of the river. You can’t have it all.


To hear more from me, you can follow me on Twitter or on LinkedIn.