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.