Internal Tooling and Archetypes

Internal tooling is not glorious work. It’s the glue that can hold an organization together, or be the thorn in the side of everyone who has to use it. You can’t really open-source the code, and even if you did it’s of minimal value to anyone outside of the organization because it’s hacked-up code to deal with specific business processes. Often the people writing it are so deep in the domain that it’s easy to lose sight of the user base and write stuff that no one wants to use or work on.

In a small company, you can get away with playing tech support for the 3-10 people who are using the programs, but as your organization grows it no longer makes sense to think of individual use cases. One thing I’ve started doing is creating character archetypes that entail several traits that are important to recognize when developing a tool. These archetypes are multi-dimensional, all with strengths and weaknesses, from which you can figure what qualities these internal tools need.

Archetype: Jimmy Junior

Jimmy Junior is fresh out of school and too confident to admit he doesn’t actually understand how the shell works. He can follow instructions, but don’t expect any leaps of intellect.

To work well with Jimmy

Instructions need to be step-by-step. Jimmy is guaranteed to fail on the one step that ‘should be obvious.’
Have a FAQ page. Otherwise Jimmy will go on Stack Overflow and learn that “turning off SSL validation fixes the problem!”
Have a chat channel/mailing list for the tool, and ensure that Jimmy’s setup is actually working if there’s radio silence.
Think of the destructive capabilities of your tool - Jimmy won’t. Don’t make something that can blow away a production database with a fat-fingering.

Archetype: Maxine Mac

Maxine is a Mac user who does UI work, and really appreciates a simple interface. She’s familiar with the terminal, and prefers stuff that Just Works.

To work well with Maxine

Use something like an internal Homebrew tap to keep installation and upgrading simple.
The default actions should be correct at least 95% of the time. Keep the number of knobs to a minimum.
The user experience should be polished. This means bugs on the common path are rare and fixed quickly.

Archetype: Archie Linux

Archie built his operating system from source, and knows exactly which kernel parameter to tweak to make YouTube videos load 3% faster. Whether you want him to or not, he’s going to send you patches so that your thing works correctly with his glibc-fork you’ve never heard of.

To work well with Archie

Up-to-date build instructions for how to build from source (and VCS, if that’s different).
Architecture docs are helpful, and the rationale for how you arrived at the various design aspects should be included (e.g. ‘we had to do X because of an integration with team Y, but we’d have preferred to do Z’).
Domain details should be included in the source, and not just in the dense block of documentation at the header of the page. Otherwise, Archie will “speed up” something and all of a sudden your office’s coffee machine will start sending spam messages to minor Twitter celebrities.

Archetype: Bonnie Bad-luck

Bonnie Bad-luck somehow manages to hit every edge case in your program. That “theoretical” integer overflow that no one should ever hit? Bonnie just got hit by it, and the release is supposed to go out in an hour. She’s got more important crap to do than troubleshoot your scripts, and wants you to get this sorted pronto. Even if you don’t think you’re writing this program for Bonnie, somehow this will be a blocker for her at the worst possible time.

To work well with Bonnie

Have a bug tracker for your internal tooling. Seems obvious, but internal tooling always seems to have the least amount of supporting infrastructure.
Your programs should have adequate logging and debugging facilities. Use versioning, and don’t trust that everyone will be running the latest version.
Have an automated release/deployment process, and as much automated release testing as you can manage. Every human you add to the release process beyond committing code creates a bottleneck that always seems to make a bad situation worse.
Don’t expect you’ll be able to pair up to fish the bug out.

No one is only one of these

These archetypes are handy for ensuring your audience is taken care of (“Jimmy Junior doesn’t know what FTP is, let alone why that’s the only choice that will work in the configuration”), but just as there’s no ‘average’ person, no one is 100% one of the archetypes. It’s important to have a variety of them (especially when there’s edge cases, such as Sarah SPARC and Andy ARM). Some users may have conflicting traits (“Lindsey Lisp wants a built-in interpreter, while Mandy Manager wants a simple one-line CLI tool”), but generally the more archetypes you have the more well-rounded your program will be (though sometimes at additional expense). It’s also important to be aware of the second-order consequences of drawing from archetypes - you don’t want to perpetuate problems in your business (or society) by setting up a problematic reinforcing feedback loop.

Knowing exactly who your audience is important - tools for dealing with an internally-developed networking protocol will have a different audience than a program to download an accounting report for your finance teams. These archetypes make it clear to both the developers and the user base who should be in mind when deciding what work to prioritize.