Five Things

Over the last few years I've managed to build a number of software tools for the day job, allowing people who work at the school-level to more quickly put the computers away and focus on the students in front of them. Having worked at the schools for nine years, I've had the opportunity to talk to a lot of colleagues and get their input on what it is that software would need to do in order to make their jobs easier. When I was transferred out of the classroom and into IT, I put a lot of this knowledge to good use to create some of the systems that students, instructors, and school staff rely on day in and day out. While I technically no longer write software for the company1, I do end up building a lot of software to help people answer questions, collate information, or otherwise get a job done in a manner more efficient than an Excel sheet can offer.

A couple of months ago some new digital textbooks were rolled out across the company. This is the first official digital textbook system2 from my employer and the response has been … less than ideal. There are over 2,000 teachers across Japan, and the vast majority of them have done nothing but complain about this newer system as it's slow, counter-intuitive, and cares more about flash and pizzaz than the job it needs to perform, which is presenting learning materials that are stored as static HTML files. Not a day goes by where there isn't at least one email waiting for me in the morning from an instructor who has gotten fed up enough with the new system that they invested some of their personal time to find my email and send a message asking me to fix it. Unfortunately, I can't fix it. The project isn't mine and, to make matters worse, I've burned every bridge with the department that was responsible for commissioning the project3. So even if I wanted to try and help by making some changes to the source and sending it up the chain as a pull request in Git, nothing would happen. Also, I'm buried in a number of other high-priority, mission-critical tasks that make it pretty much impossible for me to help.

Which is why I've chosen to simply "cheat". Some time was dedicated on Thursday and Friday to reverse engineer the API4 and I've managed to build a system that can scan the entire textbook library, grab the titles that do not exist in the digital textbook system I created, pull the HTML (and parse it into something that makes sense), and save a bunch of additional metadata to the database so that additional features like "search by grammar point" can exist. This week I'll invest two or three hours a day to getting the UI tweaked so that it looks better on a tablet, which is the primary way instructors use the textbooks, as well as ensuring that page loads are completed in under 0.25 seconds. Given that the new system needs about 12 seconds per page load, teachers will appreciate the speed increase. Hopefully by this coming Friday I can hand off this temporary solution to the right people in Tokyo who will then authorize it for release across the country.

And now it's time for the list part of this article: Five things that education-support software needs to get right.

It needs to be fast

Speed is crucial, and it's always so disappointing to see when software that cost more than my house is slower than poorly-configured WordPress site. Pages should always load in less than 1 second, ideally showing the text before any images or other bandwidth-heavy assets begin downloading. Too many applications try to be "fancy" with their animations showing spinning arrows while assets are loaded in the background. Teachers don't have time for this when they're flipping a page mid-lesson. Load the text and get the heck out of the way.

It needs to be intuitive

When people were trained to use the new digital textbook software, the sessions ran for about 80 minutes. Eighty minutes for 2,000+ teachers is a lot of wasted time and money. Training for my digital materials was not required because the interface operates like a typical Kindle, which most people already knew how to use, even if they've never used a Kindle. Also, my LMS will have links to the exact page an instructor is going to need for their class built into the person's daily schedule. Tapping a button would open the book you needed to the page you needed with the resources and notes you needed in under a second. Changing pages could be done by swiping or tapping the edge of the page. There were no animations at all. Things just changed and got out of the way.

It needs to let a teacher see exactly what a student sees

Instructor books have included student pages for over a hundred years. Teachers rely on this in order to plan better lessons. If a teacher has to guess at what a student is seeing when they open their textbook — or use any other learning material — then the support pages are nothing of the sort.

It cannot have any friction

Far too much software in the workplace contains far too much friction, disincentivizing people from using the tool in the first place. If the software is being designed primarily for use on a tablet, dispense with the dropdown lists unless they're rarely needed or honestly necessary. Arrows to toggle between pages and chapters work far better. If there are audio components in the lesson, show a scrubber bar and the length of the audio. Let people quickly skip ahead or skip back by 5, 10, or 15 seconds to quickly get to the audio segment they seek. Are there page numbers? Show them!

It must be critiqued by the people using it, not managers

The software that I've built for the day job has been critiqued a lot over the years. Sometimes very harshly. Sometimes very justly. The feedback has always been welcome, though, as it means that the person criticizing the tool (hopefully) cares enough about their job to want to do it better. The first version of my digital textbook system had a number of complaints in the first couple of months, and near-daily updates worked through those issues one at a time. This made the system much, much better for everyone5. People can sometimes be incredibly harsh when providing feedback and they can sometimes be incredibly wrong. It's important to listen and, ideally, respond back. Sometimes a harsh critique can be resolved with a little more training and a mental note to revisit a design element later.

Over the last couple of years, I've tried to adhere to these five things when building things for use at schools because it's the efforts of the teachers and students that ensure I receive a salary. If I make their lives harder, then there's no reason for them to keep me around. If I actively work to solve their problems, then everybody wins.

A lot of the software used by teachers and schools is just awful, but it really needn't be.


  1. As a "senior systems administrator", I'm in charge of data. Fortunately, this was made intentionally vague as heck by some senior managers who knew that my move valuable work is generally the stuff I was never asked to do.

  2. Funny story, I built the first digital textbook system for the company as a proof of concept while still teaching lessons back in 2014. In 2015 there were a couple of revisions made to handle some new feature requests like embedded YouTube videos and whatnot but, the demo I built in 2014 is still used today across Japan as part of the Lesson Management System I later developed.

  3. The bridges were burned because I despise office politics and petty betrayals. Far too often they would take work done by me or other colleagues and claim it as their own to senior management or, worse, describe us as an "unhelpful roadblock" because we're not dropping every other task to attend to their whimsical demands.

  4. This revealed a host of actual security concerns, as I've learned that authentication tokens can exist forever so long as they're used once in a 24-hour period. Also, by poking at the API, I've found it possible to get access to areas that my account shouldn't have access to. This "security theatre" can take place because the front end changes the menus and options based on the account permissions. So long as someone doesn't know how to use a RESTful API client, the data is "safe".

  5. It's a shame that HQ in the US has decided to throw 99% of my code away come November for stuff written by external vendors in Chicago, New Delhi, and Sydney. Alas, I'm still employed, so shouldn't complain too much.