On software lifecycles and documentation (Patreon)

I knew when I started this project that I was designing for the long term.

A little history

I first started making character sheets for D&D 3.5 more than ten years ago. The exact date is a little fuzzy; the earliest reference I can find is in November 2009. I could tell you where I was when I first showed somebody else, but the building doesn't exist any more.

The technologies I chose to use - Adobe Illustrator making PDFs, then later Scala+iText for combining them - were reasonable choices at the time. The limitations of that method became increasingly clear over the years, though, and when Pathfinder Second Edition was announced with a year-long playtest, I took it as an opportunity to redo my project from the ground up. To learn from experience and do it the way it should have been.

I already knew that the number of classes and other options for Pathfinder Second Edition would be huge - at least as big as its predecessor, eventually. I also knew that the project would take at least a year to make (it turns out even that was optimistic) and would then need to live for at least a decade after that. So that made the choice of technologies really important.

The lure of the new

Technology keeps on moving. Web technology in particular seems to be on a constant cycle of renewal. Not a day goes by without some new framework or library or platform being announced. And while any one of those new things may look exciting, they each come with an unstated risk, based on the unvoiced question: "How long will this be around?"

For example, AngularJS was released in 2010. It was pretty cool, and you could have been mistaken for thinking it was the future. Version 2 was released in 2016, and was a complete reinvention of the project. Any work done on top of version 1 would have to be abandoned and redone for version 2 - or for a different platform.

Nowadays React is top of the pile for dynamic web binding frameworks, with nearly 80% of the market and the weight of Facebook behind it; but how long will that be true? Will something new come along and replace it? Or will a new version of react force everyone to redo their work? Will Facebook be slammed into oblivion by government fines? Will a series of dangerous vulnerabilities force everyone using React to think twice about it? Will new browser features render the need for a dynamic web binding framework obsolete, the way HTML5 replaced Flash?

This question was on my mind as I started work on the new system. I decided pretty quickly that it was going to be web-based, since that made so many things easier, from simple things like printing on US Letter rather than A4, to intricate things like translations that don't look broken when a word is longer in another language. But there were a lot of choices still to make.

I've written before about the danger inherent in relying on external dependencies - languages, projects, frameworks or tools - that may not live forever. The worst possible outcome would have been to spend all the effort needed to build this project and then have that work undermined by something that disappeared or changed under me.

Another concern was that I wanted this project to be as welcoming to newcomers as possible. The number of people who understand Scala, know how to use Illustrator, and play D&D is pretty small, which meant that very few people were able to contribute to the old project. The easier the technology stack was to pick up, 

Choose your poison

I ultimately chose what might be called the lowest common denominator: use as few external dependencies as possible, and each of those carefully chosen.

The first, and most defining, dependency is the programming language. I could have used Scala, or Ruby, or Python, or C#, or Go, or TypeScript. All of them are valid choices, with their own pros and cons, and all are likely to survive for at least the next 10 years.

I chose to use the native language of the web, the language we can never be rid of no matter how much we dislike it: JavaScript.

As well as its longevity, an advantage is that JavaScript is a language lots of people are likely to know. It certainly isn't the best language, but it's a popular one.

There have been a lot of changes in the life of JavaScript. Since I'm writing this project for the future, I used the most modern version of JavaScript I could, using Babel to transpile it into the most compatible version, one that'll run on anything from a mainframe to a Pi. If the Babel project is discontinued, I'll have to rework a few things and the project will then require an up-to-date version of Node.js, but it'll keep working.

The second choice is the architecture. To ensure the most people possible could contribute to this project, I needed to minimise the amount they'd need to learn.

I could have written each Pathfinder class as a JavaScript class, but that would have meant the only people who could contribute to the project would be those who at least know JavaScript. That may seem like a low hurdle for a professional, but it's a high hurdle for the general population. Instead I chose to make the structure data-driven, so that anybody who can edit a simple text file can contribute. I chose YAML as the format, as it's one of the simplest and most friendly out there. It's semantically equivalent to JSON, but less annoying about programmery things like brackets.

The structure for combining classes, ancestries, feats etc into a single character sheet is done with a common programming technique called Inversion Of Control, which I've presented in as clear a way as possible using "zones" and "units". So for example, the combat page has a zone called "actions"; the Monk class contributes an element to the "actions" list for the Flurry of Blows action. The Monk class is a unit, and so is the Gnome ancestry, the Ironblood Stance, the Scholar background, and the Animal Companion option. By combining all the different units you make up a complete character sheet, without writing any real code.

Documentation

I now have a new technology choice to make. The project is nearing readiness, but there's one big thing lacking: documentation.

Any programmer eventually learns that code more than a few months old may as well have been written by somebody else, since you'll need to learn again how it works. I've endeavoured to make this project as clearly written, cleanly structured and well architected as possible, but inevitably there are more details in there than my little head can hold, so I'm having to refer back to the code to work out how to use the pieces I've made. I want somebody who isn't intimately familiar with all the bits of the project to be able to add to it; and increasingly that's going to mean me.

On the plus side, most of those pieces have settled down into solid working versions that probably won't need to change much. That means they're ripe for documenting.

I need to pick a format for documentation. I want it to be under source control, because that makes everything better. I want it to be something anybody can read or write. And I want it to be clear and expressive enough to describe the project.

But crucially, I need it to be something that will last. There are countless tools and formats for writing documentation out there, but that very proliferation makes me worry about how long any one of them is going to survive. I don't want to be porting my content from one format to another every year, losing something every time. Like the code itself, details may change over time, but the bulk of the source should be able to stay exactly where it is.

I haven't fixed on a solution yet. I'll let you know when I do.

See also:

• On software dependencies
• Decoupling