Write a treedme

I finally put away the holiday decorations over the weekend. When I went to pack up the artificial tree, I was again pleasantly surprised to find this diagram I’d left for myself:

Years ago, the first time I had to re-pack it, I found it difficult to get it back properly into the original cardboard box. After struggling with it for a while, I eventually sorted out the arrangement. Then, I drew myself the diagram for when I inevitably encountered the same issue again.

In our typographic work, not all little annoyances are guaranteed to come up again, and not all can be solved by quickly documenting a key process or reason behind a decision—but a lot can.

While it’s expected that open source software projects will require a README—a text file with at least a little documentation on how to run or make use of the project—I still find myself surprised when this isn’t the case with private internal projects and font source files.

For some projects, you might think that, “I won’t need to come back to this.” In practice, this is difficult to predict. Maybe a single small change you need to make, turns out to not be so small as you have to understand where your files were left as well.

If a few notes on a key decision or where the project was left might be useful later, I think it’s a worthwhile tradeoff to invest in a little documentation now, while the ideas are fresh. Even if you truly never go back to this project, the habit tends to pay off on other occasions.

Another reason might be that, “no one will need to use this other than me.” Perhaps that means your entire company is just you, or simply that the majority of the time, you are solely responsible for a particular set of font source files.

Even still, there is at least one other colleague you are going to have to contend with at some point: you, from the past.

I know decisions that I’ve made that are crystal clear to me now, turned out not to be later, when I had to revisit my own source files. I’m reminded of this observation from Philippe Creux via Godfrey Chan via Kerri Miller:

Finally, a complete and concise definition of “Legacy Code” by Godfrey Chan: code that you didn’t write this morning.

Regardless of the version control or backup system you are using, all font source files should have is a README or equivalent: a text file that anyone working on the project can open, and get some kind of introduction to working with the files, or what state they’ve been left in.

A small diagram, or a few sentences explaining a key decision, might save you quite a bit of time and frustration. Even if, especially if, you only have open those files once a year or less.

Until next time,
Kenneth