Documentation is not evil
We’ve been cranking away, and despite having a pretty aggressive sprint schedule, we’ve kept a good model to making sure our code documentation works, which in turn automatically generates our API documentation. We also have a card to make sure our “getting_started” guide is up to date and that everyone is keeping our README.md up to date , especially issues that developers have ran into in setting up their environment. But isn’t this “working on documentation”, and one of the central tenants of the Agile Manifesto is “Working software over Comprehensive documentation”? First, that is “Comprehensive documentation”, and what we’re working on isn’t and the things we’re doing is actually essential and key to being agile, and here’s why:
Ensure interactions make sense
One of the key take aways from our first retrospective is that the UI and Backend teams struggle to communicate, and while we can keep on meeting, we can’t sit in each other’s cubes for every minute. One way we’ve decided to get around this is to ensure our “contracts” or API documentation is solid, so its very clear for our internal teams what is expected from the backend, and then enhancements and fixes can be done based off of official documentation. The funny thing is, we’re not opening up our APIs yet, so why do this when its all internal? It’s following a bit of AWS’s philosophy here of not having internal, secret APIs that only the developers know. This way, not only do our internal employees benefit, but our customers will benefit as well.
Ensure people can be ramped up quickly
This is very important, making sure that you can ramp people up quickly, no matter the situation. The idea is, if you keep the documentation fresh, and ensure you’re tracking the “gotchas”, then you’ll likely avoid having another person struggle with that. Even though we’re not growing the team right now, its still important to keep this mentality, as each of us may jump around to different code repositories, and it’s essential that any team member can ramp up to the code. The funny thing about this is, this is one of the core ideas behind using Docker. Docker allows you to containerize your application so you can get started quickly on your local dev environment, but nonetheless, keeping good documentation here is important. On top of this, because we are generating our API docs from the code documentation, people looking at the code can understand what controllers are doing, and what is expected of a particular piece of logic.
Ensure everyone sees the big picture
We can get siloed easily, and even with our small team, we already have an “UI” and “Backend” team. Now we still want this team to behave as a single team, but in the end, each member is going to have a focus area. But, everyone should know whats going on. Thus we created a getting_started repository, which will have a high level overview of our development process, our architecture, and our some basic interactions between our front end and backend. This will ensure people can get ramped up quickly but make sure we don’t have “tribal knowledge”, and that its all there for anyone to see.
Ensure you don’t have documentation debt
Just like getting rid of code debt is a key component of remaining agile, making sure you don’t have documentation debt is important as well. It’s just a good coding practice to have the latest documentation available for anyone to see, and just goes to “do you take pride in your work” type of mentality that you want to have for your development teams.
I know it may be hard while you’re hacking away to ensure your markdowns are up to date or create a getting_started guide for everyone to see and learn from, but it’s essential to maintaining good agile teams, and is an important investment in your product’s future.
