Common knowledge
Four tips for creating a comprehensive technical knowledge base from a McDonald’s Software Engineer.
by David Whitcome, Software Engineer III
Imagine you’re a developer on a new team, and a bug ticket is assigned to you.
You reach out to your teammate because you don’t know where to find the process documentation. Once you have it, the first thing you have to do is replicate the issue to get an understanding of it.
You spin up the application on your machine, which means logging into your cloud provider to get credentials. You use these to generate a token in an internal app, which can take a few minutes. Once the application boots up, you’ll have to hustle to find where the issue is since the token expires after 15 minutes.
If this process takes longer, you’ll have to start this process over again.
This is clearly not an ideal way to operate and can slow down the development process.
One thing is certain: Much of this can be prevented if developers have easy access to up-to-date resources.
The know-how of building a knowledge base
With the launch of McDonald’s Digitizing the Arches strategy, there has been a lot of movement and growth within the Global Technology organization, as we position ourselves to achieve our digital ambition.
Anyone stepping into a new engineering role must become familiar with the tech stack they’ll be working with and figure out where resources are hosted. To help prevent the situation above, my team built a centralized Technology Knowledge Base to make our processes and key information about our tech and products more easily findable and manageable for our engineers.
Going through this exercise can take a little time to ensure it’s done right — but in the long run its important because it can help avoid unnecessary disruptions to development work. I know getting started can be daunting, so I thought I’d share my top four.
1. It’s never too late to automate
The most effective way we’ve found to ensure accurate and up-to-date information is to use tools that automatically update documentation, helping to eliminate most of the manual management of onboarding information. Taking advantage of common tools, such as README files, code comments, and diagrams, is also helpful.
I’m also a big fan of code linting tools that are integrated into our CI pipelines. With a linting tool, you can force readable code to be written (up to a certain point) and can reach a test coverage percentage for branches to be merged into the main. In my opinion, tests and clean code are some of the best types of documentation. If you feel that you can’t trust the documentation outside of your application, you know that you should be able to at least trust the code itself.
The documentation process is fully integrated into our development pipeline, making the information more easily discoverable and easier to keep up to date.
2. Discovery zone
Discoverability can look different, depending on the tech stack and team. My team — which is responsible for coding and deploying offers to McDonald’s Global Mobile App — has central locations where we’ve organized code and corresponding documentation.
We setup a central git repository and found that by organizing submodules into one git superproject per squad, it’s easier to see which squad is the primary contact point for each project. This has been especially helpful for new team members since cloning the superproject is a helpful starting point for getting everything up and running in their first week.
We use a designated collaborative platform for API definitions that lets us quickly search for services and API definitions. When creating cloud infrastructure using a tool that codifies cloud APIs into declarative configuration files, we add tags and ownership information on everything, so it’s clear who owns what infrastructure.
We also use an internal dashboard — that automatically updates for new applications — that shows which configuration version of each service is deployed in each environment. The automatic updates are useful for diagnosing issues that appear in different environments. The dashboard can also show the most recent deployments and if they passed or failed.
3. Keep it simple
Making your applications, easy, quick, and maybe even a little fun to work on can help put your team’s velocity into overdrive. While there may be instances where you’ll need a complicated setup process, designing your application so that a procedure only needs to be done once during machine setup can help save time in the future.
Consider a process where a new developer just needs to install the needed software-development kits and click “run” to start up the application. Maybe the application could automatically refresh authentication tokens locally, as needed. As a bonus, the simpler the setup, the easier and more intuitive it may be to transition the app to another team in the future.
4. Raise the standards
There may be times a complex business problem will require you to come up with a new proprietary solution. When that’s not the case, using common design patterns and tech may help streamline shipping features out the door. If your teammates are even a little familiar with the tech stack and design patterns, or they can find more information online, they’ll be more prepared to knock out those business-critical tickets. Using tools and coding languages that have years of documentation and resources can make a difference.
Using commonly supported and updated technology also has the side effect of having your code already partially documented. If you’re using a third-party service to manage many microservices, you’ll likely only need to maintain minimal documentation on how to work with your tech stack. The company that manages the tech typically keeps the documentation current, so developers shouldn’t need to spend their time in keeping that information up to date.
