Put Information Where Developers Want It
Every day, we create and process a lot of information, we are in the Information Age after all. Computers, phones and products create and amplify information for us. Programmers help organize and route all the information to the places people want it to go, yet we often fail to put the information we create in the right places ourselves.
We send our co-workers messages or talk at stand-up about key details about our implementation. We use Google, Stack Overflow, and documentation to solve challenges and figure out details. We write tickets, PR summaries, and review comments. We chat and think about how to solve the important problems we are working on. All this information represents our thought process and is the work of creating new information. It’s also valuable for building context within a team.
After completing all this work, much of the information ends up in the wrong place. This doesn’t have to be the case. Information can be stored where people want it to be. We can figure out where the proper place is by noticing where we naturally search for information. The information must be close to where it is used for work. Ideally in the same place we are working. Putting information as close to the area where it is needed as possible is good because it will increase the value of that information, as well as save everyone time and energy.
Putting information in the wrong place causes us to spend more time and energy trying to find it. If it is too hard to find, we may not bother to search and instead recreate it ourselves. If we do find it, it may not have the context to help us process it. Putting the information in the place where people want it creates the context that allows others to process it more easily.
As an example, instead of forcing developers to think through example implementations using a method or class themselves, or providing a tutorial to do so in the documentation, comments in the code could explain it. For future developers trying to understand a method or class, this is likely where they would look first so why don’t we make it easier for them.
This is an example from Discord.py. The comments not only explained what the methods did, but gave sample examples of the method. Instead of trying to figure out how an example would ideally work, it showed me. The pieces were right there, I didn’t have to search the documentation or look up how to implement it, it was in the code itself. The information was where I wanted it to be.
Putting the information in these places isn’t much harder either. You are the one working in the place, right now. You have already done the work to understand what needs to be done, how it connects with the rest of the program, what the context of the method or class is, and implemented it. The hard part is creating the information. Figuring out where to put it should be easy.
The key is figuring out where you are doing the work to create information and put as much of it there as you can. Think about where you wished the information was. Instead of a Stack Overflow answer or obscure forum post, it would have been ideal in your codebase. Figure out where future developers do the work, and where they check for information that helps them do the work, and put it there. This could be the code itself, a standard process document, scripts, or an example that is heavily checked or referenced. You want to help future searchers find information that is valuable.
It is easier to subtract and ignore than it is to discover. That is why you shouldn’t worry about adding too much information. Future readers can skim your content, they can skip over it, but it is valuable as an option. After all, bad comments are actually good. When you put information where people want it, it becomes the first place they check before they go searching. You could end their search before it even begins, saving them time and energy. As you think more about putting information in the right places, you get better at doing it.
Putting information where developers want it helps your information scale. It creates more context which helps developers have a better knowledge of the entire codebase. It allows developers to transition between areas, become familiar with pieces of code faster, and limit time spent searching or creating new information. As a developer, you’ve done the hard work creating the information. Maximize its valuable thinking about a good place where that information to live. Put it in a place people will want it. For developers, it should be as close to where they are doing the work as possible, they’ll appreciate you for it.