I Win

The title of this post has been rattling around inside my head for half a day despite the fact it’s incredibly egotistical and not at all accurate, but defines exactly how I feel about how the trip to Tokyo turned out. Today was an opportunity to talk about the "secret project" with a number of managers who have a vested interest in seeing a solution to a problem that teachers across the country have been rather vocal about. Two had seen it, the others had not. Less than 20-minutes into the presentation, everyone was in agreement that the demo was good enough to deploy to a couple of locations as a trial. Before doing such a thing, though, executive approval was required. The CEO agreed to a quick demo and discussion on the topic, gave it the green light, then said “I’m glad we have something to tell the schools now. Every visit has involved complaints about the ‘global system’”. My objectives were accomplished. Teachers at several dozen schools will soon have one less thing to fight with during the day. People were generally smiling and happy. The day could not have gotten better.

Yet the title of this post irks me.

Working in a company of 10,000+ people means that a good number of them are going to be incredibly intelligent, incredibly perceptive, and incredibly competent. I’ve been fortunate enough to work with many people who fit two or more of these attributes and I look forward to working with them in a productive manner in the future, too. The great thing about working with intelligent, perceptive, and competent people is that there is always something to learn along the way. By assuming an attitude of “I win!”, I risk coming across as yet another over-confident, egotistical bastard who doesn’t appreciate the efforts of others, which is most certainly not always the case1. What I presented today may help the organization in the long run, but it was done in a manner that will likely rub some senior-level colleagues the wrong way. While no rules were officially broken, generally when there are questions or concerns involving someone else's project, it's uncouth to reverse-engineer what they've done, hammer their system to extract content, then present it elsewhere in a manner that is completely off the radar.

Justifications aside, I simply cannot shake the feeling that I’ve “won”. What it is exactly that I’ve won? This remains to be seen. Perhaps I've won some new enemies. It could be that I've won the question of whether the day job should be hiring out our jobs to vendors rather than making use of the many people within the company who can accomplish various goals, be they related to software or otherwise. Maybe it's something else entirely.

What I want, more than anything else the day job can offer, is to hear colleagues say that they want to use my software. I understand this is a very captive market and that there is generally nowhere else to go. That said, by creating something that people want to use, I feel an incredible sense of accomplishment; I have taken complaints, worries, and concerns and built something else. Is it better? It's not for me to judge.

The system I’m trying to replace at the day job was created by intelligent people. The problem comes down to expectations. People at the school level in Japan expect software that will present them with a dearth of features designed to help them do their job. The system from HQ in the US checks all the boxes, but fails in execution. Mine excels at execution while failing with a simplified set features. Rather than thinking "I won", it might make more sense to look at this as a group effort and proclaim that we won.


  1. I will not lie and say that I always appreciate the efforts of others, as this is demonstrably false. There are several examples on this website alone where I say that someone has gone out of their way to help, and I’ve snubbed them for whatever reason. I am not at all a good person, nor can I pretend to be one. What I can do, however, is aim to be better today than I was yesterday. I honestly try to do this, though there are many, many examples of when I’ve failed.

Documentation

In order for any bit of complex software to be better understood and effectively utilized, documentation must be made available to the people who will use the tool. Unfortunately, documentation is the least favourite task that faces every developer. I can count on one hand the number of full-time software people I know who actually enjoy putting the code editors away to instead write complete sentences. There are automation tools out there that will try to write the documentation for you, but these can only go so far. At the end of the day, the best author is going to be someone — or a collection of someones — who have a good understanding of the system … which can certainly be a problem for tools that are created by one or two people.

At the day job I'm fortunate enough to be in a position where I get to make new software every couple of months. These are tools that don't exist one day, then spring into existence 20 minutes after a meeting that sanctions their creation comes to an end. A lot of the tools start out small with just three or four functions that are relatively intuitive to anyone who has worked for my employer a couple of months. However, as people begin to use the simple system and ask for "just one more thing", the software becomes more complex. The rules become more opaque. The emails from people asking how to do something becomes unworkable. By this point, documentation is not only needed, but late.

Near the end of last year I was given the opportunity to create a piece of software that would be used by colleagues all over the world and integrate with our HR systems. After a couple of discussions with the project owners it became clear that documentation was something that couldn't wait until later, it needed to be part of the development cycle1. The HR department wanted a Word file that could be updated easily and sent out as a PDF to everyone who used the system. I balked at the idea and suggested that documentation be built right into the application, complete with screenshots, videos, and links to the pages being discussed. The management wasn't keen on the solution initially, but they quickly saw the benefit once the feedback started coming in. People were actually reading the documentation that was going up, and they thanked the HR managers for making it happen so quickly.

Score one for preparedness.

In addition to this documentation, though, is the developer documentation. This is generally something that doesn't get seen by people but, because this HR project is owned by HR, some key people have access to the GitHub repository where the source is kept. These people have been reading the commit messages, Wiki pages, and Issues, and they're quite impressed with the level of detail that goes into the internal docs.

Writing a great deal on GitHub is nothing new for me, as it's sometimes necessary to have a single place where the rules and reasoning behind certain design decisions are stored. To help future me, I try to include screen shots and lists of reasons for why some functions or classes were created the way they were. If something is particularly complicated, then the messages in the commits will be a little more colourful than the dry words found in the Wiki or supporting Markdown files. This is something I try to do with all of my applications, as most of them start out small and simple, then quickly start battling scope creep as more functionality is built in. There's just one problem, though: there's almost nothing (documentation-wise) for 10Cv5 in GitHub.

The vast majority of the notes for v5 have been written to A5-sized notepads and I'm not yet 100% sure how this information will get shared with the world in a readable format? Scanning with OCR could work to a certain degree, but these notes are not always written with complete sentences (or grammar) in mind.

Documentation for v5 is slowly being released with more going out every few days. Regardless of how many people use the system, having it documented will make it easier for anyone to understand how and why it does what it does. Had I been a little more proactive with the v5 documentation like I have been with the day-job projects, then there would likely be less missing from the platform2. Fortunately there is still time to remedy this issue.


  1. Generally this is the rule for larger organisations.

  2. One interesting thing that I have noticed is that by writing documentation for the system, I get to revisit the core functionality with a semi-fresh mind. If something doesn't make sense when I'm trying to write it down, then that's a pretty good indication that something can be improved.

RAM Emergency

How much memory does a typical computer need in 2019? When I look at machines that are sold at electronics shops1, I'm seeing machines that ship with between 4 and 8 GB of RAM. Looking at the Lenovo and Dell websites will show much of the same. Most of the notebooks that are handed out at the day job also fall into this category, with schools getting machines with 8GB, and managers getting units with 4GB2. When I moved out of the classroom in 2016 I was given a Lenovo W541 notebook with 8GB of RAM, which I promptly upgraded to 32 because it was the right thing to do. That machine has since been converted to a development server and I'm now using an X1 Carbon with 8GB. As I've lamented, perhaps too often, the sleek little notebook is great except for one little detail: 8GB is simply not enough.

RAM Emergency

As one would expect, I've brought this up with a couple of my managers who have all pretty much said the same thing: there isn't money in the budget right now for a new machine, so try to make due with what's at hand. I am certainly accustomed to working with what's on hand, though it generally means that I try to find creative solutions to my problems. The "fix" that I currently have is to offload work to other machines. I can send large workloads to the development server upstairs to chug through or, if I need even more power, a potent virtual machine with lots of memory and processing horsepower has been configured for me to use at the corporate data centre. This means potentially transferring up to 50 gigabytes of compressed data3 to get work done. It's suboptimal, but it's better than struggling with a machine that is simply not up to the task.

Today was pretty rough, though. More than once I noticed the machine struggling to keep up with the workload. If I were doing data transformations today then I could understand why the physical memory was exhausted and the swap file was being thrashed. However, today's tasks were all about working with web development tools. No database work. No API development or testing. Just design and development. Why couldn't the machine keep up?

The company had a RAM emergency. The office had too much RAM.
— Jen Barber, Relationship Manager for the IT Department of Reynholm Industries

Sometimes I'm tempted to bring up the issues that I face when using this notebook to carry out my duties. I didn't have these problems when I was permitted to use my own hardware, a MacBook Pro with 16GB RAM and a much slower SSD running the very same version of Ubuntu as the Lenovo. The previous system I had requested was denied as it came out to 338,700円, which is just over $3,000 USD. If I'm a little more conservative and choose a similar machine to what I have now, an X1 Carbon with 16GB RAM, less NVMe storage, and a higher resolution screen for 182,488円, which works out to just under $1,650 USD. The 2019-model X1 Carbons will be shipping in June, so the current version is priced to clear.

But am I asking too much?

For the longest time I have tried to cost the company less money than anyone in IT. This doesn't seem to be the case anymore. I work an excessive number of hours overtime and the hardware that I've managed to acquire over the last three years is not cheap. All of this is in the service of the day job, of course, but there is still a cost involved. The management has already said "no" to the request, so coming back at them for the third time in less than four months could appear to be selfish or persistent in the worst way.

While it's true that I could just "secretly" go back to using my own personal hardware to get the job done, I would be much more comfortable having sensitive, work-related data on a work-owned machine. This way, if I am terminated or decide to leave the company at some point in the future, then I'll know that there's no company data on any of my machines. Wiping a drive and re-installing an operating system isn't enough when it comes to keeping a device clear of data, as there are backups that could also contain data that does not belong to me. I treat this subject seriously as it's my responsibility to protect and maintain data not just for the day job, but for a number of people I offer services to. For this reason my machines will continue to be used for non-day job tasks. In the meantime, it will probably make the most sense to continue doing what I'm doing, working with the tools I have and finding ways to make it all work. When it comes time to discuss this year's performance with the management team, it may be possible to bring up the topic again.

Besides, I can always use the occasional system sluggishness as an excuse to get up and walk around; something I don't do nearly enough of anymore.


  1. Never buy a computer from an electronics shop unless it's an absolute emergency. You'll pay through the nose for something that's worth less than half of the amount you forked over. Buy online if at all possible.

  2. I don't understand the logic, either. Outlook alone will consume all of this just to start up, nevermind what the browser(s) and operating system want.

  3. I work with a lot of databases. Right now I've been tasked to perform a number of data migrations for corporate offices around the world.