What are we looking at?
https://github.com/Kingcom/armips
ARMIPS is an assembler for video games. It’s a program that takes code written by a human and puts it all together into a package that a video game console can run.
I came across this while doing some game development of my own — I had a bunch of assembly code that I wanted to put together, and ARMIPS is designed solely for that purpose. And even as someone with a hobbyist background, I could not make heads or tails of this product or how to use its most basic functionality: compiling code.
Thanks to a few friends who work in computer science, I was able to figure it out, and it turned out to be extremely simple! The instructions were obviously written to an audience who already understood the ins and outs of assembling code, but with a little rewriting, I believe anyone can learn how to use it in five minutes or less.
(Disclaimer: ARMIPS is open-source, not a commercial product, I don’t own it, and I am not affiliated with the project in any way.)
The Problem
Problem 1: The landing. If you’ve never used GitHub before, I know from experience that clicking that link presents immediate confusion. GitHub is a site that software developers use to store their source code and distribute programs. When designing a webpage, a core rule of thumb is that a user will take about seven seconds to find what they’re looking for before clicking away.
There are some very user-friendly GitHub pages! ARMIPS, though, is in a very unfortunate situation: not only is the user presented with confusing information (a list of files and folders), but the most obvious action they might take (downloading the files shown) not only won’t help, but will hinder them in using ARMIPS correctly. This front-and-center list of files on every GitHub page is actually a list of files used to build the program, not run it. It is virtually useless to an end user, and yet easily tricks the inexperienced into thinking they have downloaded a faulty product.
Problem 2: The call-to-action. Scrolling down, we come to the written part of the GitHub page. Here we can find information on the program and how to use it, along with the actual download link, labeled “Automated builds”. The button draws very little attention to itself, and without prior experience, it’s hard to say whether the program is automated or being built automatically, or what a “build” even is.
Problem 3: The audience. After a very sparse explanation of what ARMIPS does, we are told it runs on a command line and how to do so, followed by other features it offers. Speaking from experience, there are two main groups who would end up on this page.
First, there are the untrained hobbyists. That’s me! Modifying games using tools made by other people is a fairly popular hobby among gamers, and you can create extensive multi-year projects without ever writing a line of code yourself.
Second, there are the trained programmers. With a background in computer science, these users know how assembly code works, and they’re interested in working directly with it.
The first mistake ARMIPS makes is saying ARMIPS “runs on a command line”. The hobbyist group, like myself, hits a brick wall right here. Command prompts are useful for programmers, but the average Windows user today will have little or no reason to ever use a command prompt, except maybe running single, very simple commands.
There’s no step-by-step for how to do this, and furthermore, this is actually false. All you need to do is take your main file for compiling, just drag and drop it onto ARMIPS.exe, let it run, and you’re done. It’s that simple.
The second mistake is launching directly into instructions for optional ways to use ARMIPS. Specifically, these are for debugging code. Unless a user is actually writing assembly code themselves (which is notoriously obtuse for the untrained), they don’t need to know this. While useful to the programmer group, the hobbyist group is seeing more information that draws attention away from what they’re actually looking for.
The Solution
So, what have we learned so far? ARMIPS, like a lot of other technical programs, has two audiences that both need information. The less-advanced users need a quick how-to, and the advanced users need complete documentation so they can effectively problem-solve. This is a very, very common situation in software distribution, and digital experiences in general.
The tried-and-true way to solve this is by dividing your info into groups, then putting them in a hierarchy from most simple on top to most complex on the bottom. To understand this, step into a customer’s shoes. People with the least knowledge are way less likely to know exactly what they’re looking for, and they’re the most likely to leave and try somewhere else (e.g. a competitor) if they don’t find it quickly. However, people who know more are more likely to know what information they need, and they’re better at figuring out where it might be. Neither group is right or wrong — they just have different needs.
What to do: In ARMIPS’s case, we would first make a large “Download Latest Version (version number)” link at the top of the written section, where everyone can see it. Second, there would be a short step-by-step, instructing the user to simply drag-and-drop the main file of their source code onto the ARMIPS executable. Further down, after a clear divider, the more technical information about ARMIPS’s other features would follow. This way, both groups can tell what they need to read. The hobbyist users will know what they’re expected to understand and what they’re not, whereas the technical users know what they can skim and where to search for what they really need.
One Last Thing
While bifurcating your audience experience like this is all well and good, it’s really important to make sure neither side gets left out in the rain. In a lot of cases, the ARMIPS problem is reversed — websites and software are all-too-happy to walk you through the most surface-level information, but any details under the hood are hidden, outdated, or don’t exist. Don’t do this! If you’re like a lot of tech companies, both you and your customers want to minimize time and money lost on customer support. Technical documentation is how you empower customers to solve their own problems. Whether you’re selling B2B or B2C, you’d rather they get over any speed bumps with a quick search, a text to a friend, or a visit to their own IT department. So update and upload those docs and manuals, no matter how dry they might be, and know that you’re treating the customer right.