Apep and Ra: Seven Intensely Practical Tips For Organising Setting Documentation for Narrative Games

I saw this tweet:

and I started responding, and I found I had a lot to say.

My perspective and, I guess, credentials: I ran Failbetter for seven years, and I’ve worked with about a dozen other studios and teams, AAA and indie, with habits ranging from the excellent to the dreadful. This advice skews indie, but it’s relevant to both ends. The struggle to keep documentation useful is the struggle of Ra with the serpent Apep. There is no enduring victory; but if you cease to make the effort, then darkness covers everything. Here are some weapons I’ve used.

1. Don’t Repeat Yourself. This is a principle from the software world: “Every piece of knowledge must have a single, unambiguous, authoritative representation within a system”. If you have the same piece of information in two documents, then every time it’s changed or expanded, you will need to change it in two places; five documents, and you’ll need to change it in five places. This never happens reliably. So you want to keep each piece of reference information about your world in one place.

Like all principles, this isn’t always achievable. There will be repetition and overlaps, constantly. But when new team members come across inconsistencies in your documentation, they will cease to trust your documentation; when existing members realise the documentation is out of date, they’ll write new docs rather than fix the old ones. Writers’ first instinct is always to write new documents, and it’s a benign habit that needs to be kept in check, like gnawing.

2. Make the system self-documenting. This is a natural extension of DRY, above. When you can avoid separate documentation, and put everything in the system [source code,  assets, content files, data…], do so. Fallen London and Sunless Sea both use a SQL database behind a CMS to store content. Cultist Simulator uses multiple JSON files. Both of these are a good compromise between human and machine readability. Using a database + CMS was possibly overkill, but I wanted to build something that a good-size team would be able to search and update for years to come (I just did a quick count of the people that I know have worked on it, and stopped at twenty). I’m more relaxed about Cultist Simulator, because the writing team might never grow beyond me, but the setup is extremely casual-modder-friendly, and I do store information directly in the files wherever I can.

Again, this is an ideal. You can’t put half-formed ideas in the system; you may not want to put secrets in the system; you will want to keep lists and summaries.  But you want old and new team members to be able to say, definitively, what is actually in the game world, quickly and easily.

3. Treat ancillary documents as scaffolding or booster rockets. Every writer/designer I’ve worked with produces acres of screen or paper or whiteboard work while they work out what they want to put in a project. Most of this will not go in the project. I used to get depressed about this, because so much gets thrown away in a half-finished-feeling state, until I realised that these things are just the external manifestation of the work going on inside the team member’s head – prosthetics to hold the information that doesn’t fit in their brain.

Sometimes, the scaffolding gets treated as reference material, because people are reluctant to throw away the documents. Keep them if you like – they’re useful to refer back to and ask What The Hell Were We Thinking or How Did We Get Here or Can We Recycle Some Ideas – but make sure they’re clearly marked as working material. In particular keep them away from new team members, who won’t have the background to realise what’s old and what’s current. I’ve broken this rule on numerous occasions, and I’ve regretted it.

4. Distil to patterns. Where you can, document the patterns,  not the details. Here’s something I wrote about historical accuracy in Fallen London, way back in 2009:

“As a position statement, the approach in [Fallen London] has always been not to be openly anachronistic but not to be too fussed: so there’s a music hall culture that’s more of the 1890s/00s than the 1880s, we slip in and out of Victorian turns of phrase, we probably have hundreds of other mistakes, but we don’t have electric street-lights or Marxist-Leninists.”

I could have given a list of several dozen specific anachronisms that were permissible, and others that were not. In other contexts, I tried exactly this white-listing approach for setting details. But the rules that survived were the patterns, the guidelines, not the white-lists. New team members read and retain guidelines where they cannot read and retain lists. This is not a real world: you want to produce material that is persuasive, consistent and appealing, not ‘accurate’. Sometimes you need (e.g.) timelines to manage consistency, but the lesson from there is that you should never add a date without a good reason, because using that date constrains you to getting it right forever.

5. Choose tools that respond quickly. Delays when a documentation system is opened have a hugely disproportionate effect. If a writer knows that something will take more than about half a second to open, they become immediately less likely to open it and refer to it, let alone update it.

Text files, bam, great. Word files stored locally in eg Dropbox, still pretty good. Google Docs, delay of a couple of seconds…. you’ll notice people are already a little less likely to open them. Wikis, ugh. Most default installations of most wikis are >5 seconds to load a page, sometimes longer, and the same when you switch to edit mode.

“So I’ll tell my team it’s important.” Good luck with that. My experience – over almost twenty years with developers and writers who’ve ranged from the slapdash to the agonisingly conscientious – is that tool speed makes a constant, significant difference, even with the agonisingly conscientious ones . Task-switching, when you’re doing something intense like writing or coding, has a noticeable mental cost. Waiting five seconds to switch tabs wears on the nerves.

6. Choose tools that encourage brevity. This is one of the reasons I like spreadsheets. Writers, as I said above, write in the same way that gerbils gnaw. Leave one alone in a room and it will be full of words when you come back. The writing impulse is to produce in quantity.

But the lengthier a document is, the harder it is to absorb and the harder it is to keep updated. Find formats and tools that encourage brevity.

Spreadsheets are a really good way to do this. There is a constant pressure to keep text short, without anything as specific as a word limit; and there is a constant benefit from seeing many short pieces of text in a scannable, searchable format.

7. And be realistic about skills. There is a heavy overlap between software developers and writers of interactive narratives, especially at the indie end of the scene. Many of the skills, aptitudes and disciplines that make a good interactive writer also make a good software developer.

But the overlap is limited, and I’ve known plenty of very good system-thinking interactive writers who can’t code, and plenty of coders who can’t write. You may not want to assume that an average new team member will understand conventions, tools or technologies that seem trivial or ubiquitous to coders. You also may not want to assume that even someone with passable coding skills will have good, tidy or maintainable habits.  You can just insist that you’ll only hire people who are both good coders and good writers, but that’s unlikely to be practical, and you’ll miss out on a lot of usefully diverse perspectives. (This is a PITA when it comes to 2, above – Make the system self-documenting – because it limits what’s practical. Sorry, that’s the breaks; you may just have to privilege accessibility over versatility in your design).

This is particularly true of version control systems, which can be very hostile to non-developers, once you get past basic update/commit scenarios. You want to be able to see who last updated something; it’s nice to be able to look at earlier versions. Google Docs gives you that. You won’t need a fully-featured VCS (unless your workflow requires it for other reasons, but that’s a whole different vale of pain).

Related: some grumbling about counterproductive instincts in ‘worldbuilding’.

[This article was first published on our blog at weatherfactory.biz]