All your project work, always available, in one place.
Lately, I’ve been thinking a lot about how important it is to keep software artifacts as close to the source code as possible. It’s even more important on large software projects.
Most of the projects I’ve encountered in my 26 year career in software development have suffered from artifacts like the product backlog, support documentation and decision logs being scattered across multiple systems like jira, and confluence. I’m not picking on Atlassian here, it might be Microsoft products. The point I’m making is that it disrupts the flow of the team when they have to hunt down the work and the disparate systems of record don’t reflect reality.
I’m currently working with a great team of over 40 people on a public sector software project. Over the course of a day, I find myself logging into jira or confluence at least 5 times. I can understand the need for security, so maybe that’s a bad metric, but compounded with the fact that the source of truth about why the software exists and what it does are in the code and tests, it makes no sense to keep artifacts scattered across systems.
As software engineers we learn that the best documentation is code that has a screaming architecture and is readable. Every developer on the team should know where things are because it’s obvious, just by looking at the directory structure. This same rule should apply to the backlog and other artifacts.
It’s 2024 and in our desire to build a better way of doing things, we’ve forgotten that we too are users of the systems we create. Maybe we don’t come in through the same entry point as the users we build for or do the same work they do, but we are working in the same system. The next time you go out to a good restaurant and have a chance to look in the kitchen, you’ll see every tool needed to serve you a great meal in a convenient location. The kitchen knives aren’t kept under the bar.
Software engineers keep things close through instinct. Things like TODO comments and readme files are great examples. Some people say the best developers are lazy. I say they’re smart. They don’t want to spend time looking for things, they want to build. Years ago, I started building imdone, a file based backlog and kanban board that I used to keep my people management, enterprise architecture and administrative work organized. I’m still using it today and so are over 400 customers I call smart people. My dream is to live in a world where it’s dead simple for software engineers, product owners and everyone else on the team to keep important work artifacts well organized and close to the source code, so we all know what’s what.
