In Space, No One Cares About the Documentation

Meditations on the Future Dispatched from Silicon Valley, San Francisco


In Science Fiction circles, we readers are always awarding points to authors who manage to make reasonably accurate predictions. Being able to introduce prescient ideas in fictional words means that the author must have become close to some frontier of knowledge and reported it back to the rest of us. In today’s world, news of scientific and technological advances travels quickly, unencumbered by gaps in communication structure or a lack of undersea cable. Practically speaking, knowledge and discoveries move more quickly from the frontier to the lands laypeople inhabit than ever before.

The ease of spreading the word about new developments means that the world is largely equal parts excited and scared by current technological trends. In other words, it’s a good time to consider what the extrapolations present in (as well as those that are noticeably missing from) Science Fiction can reveal to us about the future.

Coding (and documentation) during space travel

Picture1A Python implementation of the Mersenne Twister, a celebrated random-number generator, copied from Wikipedia.

Don’t be alarmed, but there is a Silicon Valley analog in most major urban areas. Santa Monica’s analog is called Silicon Beach, Tel Aviv’s is called Silicon Wadi, Amsterdam’s is called Silicon Canal; the Dublin tech area is known as Silicon docks whereas in Scotland the analogous area is called Silicon Glen; and the technology ecosystem in Kenya is known as Silicon Savannah. That many urban areas have a tech sector is not a new phenomenon, even though the tendency to reward and glamorize engineering is.

Yet despite an increasingly large cross-societal focus on programming, celebrated science fiction (including older books like Herbert’s Dune, and Asimov’s The Foundation series, as well as newer television shows like Firefly, and The Expanse) often contains nothing more than a cursory discussion of people coding in space (aka on a space-ship, or on another planet). The most notable exception is A Deepness in The Sky, in which Vernor Vinge explored what might happen to computer programming in several millennia. In A Deepness in the Sky, space-faring ships employ linguistic archeologists to dig through innumerable layers of old code and modify them as needed. Presumably, the reason any discussion of coding in space is avoided is that coding seems like it would be a boring spectator sport. In some cases, coding consists of slogging through mundane, detail-oriented procedures, and it is nearly impossible to make the watching of people working through mundane, procedural details entertaining (with the possible sole exception of HBO’s The Wire).

What’s curious is that from a story-telling point of view, one way to make programming more exciting is to have different characters complain about the documentation and go on rants. To determine if real, non-fictional people will both code and complain in space, let’s examine the reasons why they might do so.

Despite the lack of TV-made, dramatic moments that can occur while arranging symbols on a computer screen, there are a few reasons why future space-faring people will write software while hurtling through vast expanses of nothingness. The traditional justification for why people might code in space goes something like “astronauts may need information-manipulation tools that haven’t been prefabricated to make sure things go smoothly.”

While a perfectly good reason, allow me to submit an additional one: working on a programming project can solve more psychological issues than it creates.[1] If you take reasonably bright and active minds and send them to Mars for a multi-month voyage, giving them enough to do while they hurtle through the vast nothingness engulfing the universe will be important. Sure, the databases of the spaceship might be loaded with television, movies, music, books and a simulation of what Reddit might be like over the duration of the journey. However, transatlantic flights also have similar types of entertainment, and transatlantic flights can be boring.

In general, we get bored when we are in want of certain types of stimulation, or we are unable to grow from utilizing our capacities for creativity and production. Thus, one way to prevent boredom is to have people make measurable progress on a shared goal. A multi-person software project is a nearly resource-free way to cure boredom, give space-travelers a shared and complex goal as well as engender a sense of meaning and accomplishment. (By this line of thinking, a regular writer’s workshop in space could also accomplish something similar, and it might be advisable to do both so as to prevent burnout on either one.) At least on a spaceship you won’t have to debate — as is currently in silicon-valley-vogue — about the benefits of an open-office plan: the constraints of the spaceship will dictate who sits where.[2]

If you don’t code, you may be unaware that programmers spend a surprisingly large chunk of time looking up how to do things, reading the documentation of languages and the software packages they are using, looking for obscure blog posts that solve a closely related problem, referring back to old code from a different source that solved something similar and so on. In short, some programmers (myself included) would go so far as sourcing a Sumerian cuneiform tablet if they thought it held a shortcut to writing a login/logout authentication system for a website.[3]

Now I have yet to meet a programmer or data scientist who has been entirely satisfied with the quality of documentation of the tools they use to make their programs.[4] In fact, there are entire companies — like StackOverflow — that are predicated on a general failure to sufficiently document programming languages. This suggests that if individuals on spaceships will be coding, it is no stretch to say they will also be complaining about the documentation.

Though there are many reasons why poor documentation is common, let’s cover two – one social and one technical.

Socially speaking, the quality of documentation falls prey to self-selection effects, which essentially boils down to the fact that creating a programming language, using a programming language, and writing are rather different skills. Specifically, any person who look up documentation isn’t just trying to figure out how a small piece of the coding language works, they are trying to solve a larger problem. Often, documentation only covers the former. In fact, many of the people who look to documentation would benefit from easy-to-read tutorials on advanced domain-specific topics. However, those who need this kind of instruction the least are the exact type of people likely to create new programming languages and the documentation for it. (Another way of saying this is that there is often a large gap between the introductory tutorials and the kinds of tutorials that would be immediately helpful for solving whatever it is one is working on.) In other words, learning how chisels work is not the same thing as learning how to sculpt, and when coding, so to speak, there many degrees of sculpting finesse one can attain.

As for the more technical reason, cue what I hope will one day be called Warfel’s Carpentry Theory of Software Development. Creating software with a programming language of your choice is like walking into a wood shop that is fanatical about the efficient use of raw materials. Once in the shop, you then use the available tools to build the thing you want. Except that every tool in the wood shop (including the bandsaw, the joiner, the drum-sander, the hand-planes, the tables, the clamps and even the sandpaper) is also made out of wood. By trial and error, it has been determined that though whittling a canoe with a bandsaw is possible, it’s not worth the effort — you end up generating sawdust and taking a lot of time. Instead, it is more efficient to first make a wooden “canoe-maker” tool, and then use that to make your canoe. Continue this line of pursuit, and your final creation will be made out of wood, made with tools that you’ve also made out of wood, and so on.[5]

To make this whole thing more complicated, you aren’t the only person in the shop; people who bought a membership are busy trying to make tools that might be more efficient at carving the front end of a clog, or the top of a piano, or whatever else they are interested in.[6] And at each workbench, each person has a complex, multi-step process they use to create their final meta-tool devices. To make a clog, for instance, first you need a clog-making tool, and to make a clog-making tool, you need a device that makes a clog-making tool, and so on. It’s easy for developers to explain how they made the leap from the second to last tool to the final one. It is much harder to step back and explain what their thing does to someone who hasn’t built the same tools they have, especially because — to break out of this metaphor here — some of the tools are mental tricks and shortcuts learned over years of experience.  These tendencies often contribute to other people missing out on the context of all of the intermediate steps that went to developing the tool.

Thus documentation is often poor, and we can safely conclude that future spacefarers who create software to prevent boredom, madness and other maladies will likely be complaining in space. However, coding in space is only one plausible aspect of the future worth considering. In addition, one thing science fiction generally gets right is devices that respond to the intention of the user with minimal learning on the user’s part.


[1] Assuming, of course, said programming project is neither organized via Microsoft PowerPoint nor written in multi-threaded R. Using Microsoft PowerPoint to organize and keep track of a complex software development project is like using a movie projector to decorate a cake. In both cases, one’s goal is almost entirely divorced from what the tool in question is good at. R, on the other hand, is perhaps the only programming language that feels as if it was made by pretentious statisticians. Not surprisingly, R is great for analyzing data, and terrible for just about everything else. Furthermore, R makes some foundational assumptions about the nature of information manipulation that makes multi-threading (also known as convincing the computer to engage in neurotic and frenetic multitasking), difficult.

[2] In an attempt to figure out if any astronauts have actually programmed in space, and thus had cause to complain about the documentation of the programming languages they used, I reached out to NASA and celebrated programmer Peter Norvig. I haven’t heard back from them. In the meantime, plenty has been written about the documentation of how to use the space ship or what to do on the space missions — see here

[3] In fairness, authentication is tricky. It involves things like figuring out how to verify a password without matching it against a literal copy of the text of the password. (The idea being that should a hacker break into the website, they shouldn’t be able to look up what users’ passwords are.)

[4] From my personal experience, the Python package SciKit-Learn has good documentation. According to my friend Vynce, Perl 5 had “amazing docs.” 

[5] This is the story that is told, at any rate — at some point, the tools used to make the tools available in the wood shop will require other trappings like a power source, or, heaven forbid, old Fortran routines. 

[6] Those who are willing to give their meta-tools away for free call themselves “Open Source Contributors.” (In rarer cases, people will use these free tools to make and give away software for end-users.)

Leave a comment

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>