Make Your Internal Tools Easier to Use Than The Alternative

One of the largest parts in my role as an Operations Engineer is creating "internal tools". This means coding features in our app (or building totally separate apps) that a customer never sees, but are instead used by team members to perform administrative duties, or support customers.

I strive to make these internal tools simple to use and useful. This means building them well.

Don't mistake clever code, a novel approach, or getting to use a hot new language as a well built internal tool. A well built internal tool should make people say "Why would you do it any other way?" A great internal tool will be easier to use than the alternative.

There are 3 big ways you can help yourself build better internal tools:

1. Don't build it for yourself
2. Over document
3. Make the alternative harder

An internal I built for Chargify that I'm particularly proud of is called "Admin Functions". Pre Admin Functions, we kept a document of "recipes" you could copy, paste, and modify in the console to make needed changes. Obviously entering arbitrary code into a production console is less than ideal, so thus Admin Functions were born.

Admin Functions solve this problem by allowing those same actions to be carried out through an auditable, authenticated, access-level-scoped, common-flow UI interaction. We'll have a future blog post going deeper in depth on the Admin Functions.

For now I just want to focus on the 3 big ways to make better internal tools I mentioned before.

1. Don't build it for yourself

An example from the Admin Functions: I built a nice searchable index page to display all the admin functions with a "Title" and "Description" column. I never thought to add a "Danger Level" column.

I was building this tool for myself. I knew how dangerous any one of these Admin Functions would be because I knew the underlying code that was being run. However, the support staff that would be using these every day did not know that.

And so, after I launched the first version of Admin Functions, one of the very first things I was asked to add was a "Danger Level" column that would let someone know at a glance whether the Admin Function they were about to perform was reversible, or had particularly dangerous effects if run on the wrong records.

I could have had this feature from the start if I had remembered that I wasn't building this tool for myself. I should have enlisted the feedback of the actual people I was building it for.

2. Over Document

• This seems simple enough, but is very easy to overlook. No matter how well you build your tool, it will never be as intuitive as you think it is. You will need to write documentation.
• Anticipate people's questions, try to have answers for them already written out wherever your team keeps documentation when you first launch your new tool.
• Record a video/GIF of you using the new tool to give people a quick TL;DR of what this new tool does.
• When someone asks you a question that your documentation doesn't answer, add it to the documentation. Even if you think "nobody else will ever ask this".
• If you find multiple people asking the same question, and you feel that it's already answered in the documentation, you need to reorganize/rewrite your documentation. If people are having trouble finding the answer, then where you put the answer doesn't make sense to them.
• Don't be afraid to repeat yourself. The more places the same information is, the easier it will be for people to find the answer to whatever question they have about your tool.

3. Make the Alternative Harder

I know, I know, this is cheating. Sometimes you have to cheat.

When would you make the alternative harder? Admin Functions again are a good example. Remember, they were meant to replace the need to open the production console and copy and paste arbitrary code into it.

No matter how nice I made the UI or user flow for Admin Functions, it would always be easier to just paste a couple lines into the console. But we didn't want people to keep doing that because it was just so much more accident prone.

So, I made it harder to copy and paste code into the console in conjunction with releasing Admin Functions. I made our console read-only. No longer could you paste in code that would do any kind of write operation. If you still needed to do so, you would need to log in to the console, get your code peer reviewed, approved, and then complete a security prompt on the console before disabling read-only mode.

Suddenly, Admin Functions seem pretty easy (and less scary) in comparison. Just open up the app, click the function you want, enter a couple params and you're done. No need to get the code peer-reviewed, no security prompt to fill out, no console to log in to.

By locking down the console, I had made Admin Functions easier to use than the alternative. And that's the whole point.