Write Admin Tools From Day One

UPDATE:  I gave a talk expanding on this blog post at EMPEX NYC 2023.

The Problem

Writing useful features for your users is key to a successful product.  It makes sense then that you should maximize your time writing features for those users.   This approach is very effective at the beginning of a product's life, but over time, you may find you are spending more time maintaining the product that developing it.

Some of the biggest development time sucks can be:

• Tracking down the cause of unexpected behavior.
• Fixing data.
• Answering user, or team member questions.
• Running maintenance scripts, or other ad-hoc tasks.

The "Oh #&@$" Solution

These small support tasks start to add up, and there is no easy way to offload the work to product, or support.  You and your development team reach a breaking point where you must start prioritizing administrative tools. Unfortunately, you will slow down your new feature development even more in the short term.  It will take time for those tools to be developed, and take effect to lower your support load.

The Real Solution

The only way to avoid a growing support problem or a temporary slowdown is to allocate time to develop admin tools from day one.  Provide useful administrative tools for your team, and other internal employees to leverage.  Ideally, you want to write administrative tools along with the features.  Include supportability in the acceptance criteria, or design documents. There will always be some support load the tools won't be able to meet, but overall, the load will not grow.  There is always time to improve the tools built into the development budget.  

Ideally, the time allocation should look like this:

The time allocated to support will never grow out of control.  Issues will crop up that the tools cannot handle.  These can be remedied each iteration using the ongoing budget for admin tool improvement.

What Tools To Provide

Admin tools come in various shapes and sizes.   Here are some ways to provide support capabilities to your non-engineering team members.

System Visibility

Many times, a support request to engineering is "why did this thing happen?".   This typically stems from a lack of system visibility to the rest of your team. 

An engineer may solve this by logging into the database directly, or poking through files stored on disk, or a cloud storage provider.  This could also mean combing through logs.

To support your team, provide them with saved views to logs.  Maybe they are filterable to a specific user's actions.  Provide them with an analytics user to a database replica that has limited permissions.  Give them wiki page or a short demo video on how to find basic data themselves.

One unique solution I've used is to provide a Postman Collection that was shared with the team.  Rather than describe the whole API, it had specific calls saved that were useful for support.

Data Modification

Once a user determines what is wrong, a common request is to modify sorted data.  This could be an incorrectly formatted email address, or other data that is trivial to fix.  

To support this use case, I suggest using a 3rd party library that exposes a CRUD for internal users to modify system data.  There are usually a handful of choices per stack.  For Elixir, there is Kaffy, and Torch.  For Laravel, there is Nova. For Python, there is Django Admin.  Typically you can expose CRUD for specific models, and even search / filter on model list views.

Support Actions

Another feature of most 3rd party administrative libraries is the ability to execute pre-defined support actions.   This is a great capability that works great for ongoing support tool development.  If a support issue crops up more than once, you can easily create a new action to remedy it.   Since there is already a whole framework providing this, you most likely just need to write one new function that takes in a few parameters.  The admin tool framework will provide the authentication, and framework to execute it.

Audit Trail

One key thing to consider when exposing administrative tools is to capture an audit trail.  If users are able to modify the state of important or sensitive data, it should be logged who changed what, and when.  This could be implemented by logging, or database triggers.  This may not always be necessary, but if you have a larger team, and multiple people will be modifying things, it should be prioritized.

Where To Start?

Here are my recommendations for taking a support first approach to development.

1. Leverage a 3rd party admin framework from day one.
1. Provides authorization to data / actions
2. Provides visibility into data so team can answer questions on their own.
3. Provides framework for developing and executing support actions quickly.
2. Provide other visibility tools such as:
1. Saved views of application logs.
2. Database user with limited access to data.  (Replica or warehouse is best).
3. Limited access to other systems, such as email providers, media storage, etc.
3. Write the minimal amount of support features, as you can easily add in more once your basic framework is set up.
4. Provide wiki, and / or video tutorials on how to do basic support actions.  My favorite way to do this is to just record myself testing the feature, and upload it to a support wiki.  

Conclusion

I hope this guide helps you understand the importance of including support tools for your team from day one of development.   I've found it to be a huge time saver.  When I've worked on very small teams, it frees up my time as I'd be the only one who can do the support work.  When I've worked on large teams, it's saved me as there would have been too much request volume to deal with.   If you have any questions, just ask!

- Andy Glassman

LinkedIn

Twitter

SwayDM