Are IF design documents different?

[BitterlyIndifferent (Peter M.J. Gross)]

I’m familiar with the imitable process of Ryan Veeder and Emily Short’s thoughts on idea to implementation, but I’m curious about the differences that people have encountered in planning/designing interactive fiction vs. other types of games.

The main thing I’ve found is that there are a lot of different approaches to design documents. Do people try to do their planning inside the game file, so it’s all in one place? (Everything is text!)

Or have they found other tools that are useful for keeping themselves organized? I have not been very good at figuring out how to stay organized in Inform’s IDE.

[severedhand]

If I’m not able to magic up a chunk of the game in my head, I plan it on paper. This involves a scratchy map and jotted notes and ideas.

The value of not doing an initial stage digitally is that digital output is always subject to revision that constantly makes all former versions invisible. You can’t even type one sentence without correcting it.

The piece of paper retains scribbles, older versions of the same idea, shows how hard or easy something was to come up with at a glance. On the other hand, every word proc doc looks like every other.

You could use track changes or something, but the resulting mess doesn’t cut it, for me.

At an intermediate stage (elaborating upon the piece of paper, only if necessary) I might then type some details into either the IDE as comments, or a word proc doc.

@BitterlyIndifferent

The main thing I’ve found is that there are a lot of different approaches to design documents

I’d say a lot of the docs cited in your blog post by famous designers (EDIT: Ok, maybe not so famous – while writing this I brainsmooshed together the Grim Fandango/Zork parts and the other parts) don’t apply to IF because in IF, without a pile of graphic and sound assets to worry about, you can change many things quickly and at low cost. Implementing a system deeply and then undoing it is high cost, but don’t make that mistake… I mean more like… you don’t have a 3d artist who’d have to work up a character while you’re designing other things, and who then finds their work instantly wasted if you change the brief. In IF, you’ll just erase the old description and write a new better one you just came up with.

@BitterlyIndifferent

Or have they found other tools that are useful for keeping themselves organized?

Now that my WIP is very long, I have a glossary and ideas file in a Scrivener doc. I had visions of this being a great reference, but actually, the bigger the game gets, the less organised the doc becomes. It’s too hard to know what things in it are Lore, and what things are ideas for lore that I changed after I added them. So I don’t treat it too strictly any more.

@BitterlyIndifferent

I have not been very good at figuring out how to stay organized in Inform’s IDE.

I can’t even use the index (WIP’s in Inform 7) much now that the game’s been broken up into extension-based chapters. Their contents aren’t indexed on a compile. I admit I’ve found this has freed me up some from my organisational mentality. I don’t need as much organisation as I used to have.

-Wade

[DavidC]

My old company Textfyre implemented both its published games from Word design documents.

Textfyre Design Documents

[SomeOne2 (Max Fog)]

I do everything on paper, but this:

@severedhand

you don’t have a 3d artist who’d have to work up a character while you’re designing other things, and who then finds their work instantly wasted if you change the brief. In IF, you’ll just erase the old description and write a new better one you just came up with.

Perfectly fits what I keep thinking about. When I watch movies, people keep saying "why don’t they just refilm this or so? And I agree, but then I realise I’ve been thinking in IF terms, where updates are easy and don’t need a whole Director’s Cut and so to justify what I’ve done.

On the “design side”, I write in paper, with scribbles that only I can understand (unfortunately), and arrows pointing off to pieces of text that are either massive, or tiny to fit inside/between the letters. I’m not even joking.

[zarf (Andrew Plotkin)]

@BitterlyIndifferent

The main thing I’ve found is that there are a lot of different approaches to design documents .

Certainly true.

In my (limited outside of IF) experience, the doc is built around whatever the game does. If the game has combat, design includes a lot of spreadsheets describing combat items or moves or enemies, because you have to balance that stuff. Sam Barlow has given talks describing how he designed Her Story, Telling Lies, Immortality – he’s got a lot of spreadsheets showing which video clips include which words or images, because that’s how everything is interlinked.

My System’s Twilight design folder is all sketches of puzzles and an overview map.

All of my IF design sheets are plain text files, plus a hand-drawn map. I don’t work inside the game file because (a) the design doc comes before coding, and (b) I want to keep them open in separate windows as I work.

[J_J_Guest]

I used to write in notebooks. Most of my early games have a notebook each containing maps, room descriptions and dialogue, to-do lists, notes about puzzle construction and so on. Recently I’ve switched to using Google Docs or Keep Notes for the text, because I can write it on my phone whenever I think of it and copy-paste it into the game later. There’s an extensive section of commented-out notes at the foot of every one of my I7 games. I’ve switched to Trizbort for designing maps, but that doesn’t mean my desk isn’t strewn with Post-it notes with bits of map on. A lot the planning is done in my head. It’s all a bit slapdash really, I’ve never been much of a systematiser, except when it comes to crunch time and I really have to focus.

[manonamora (Manon)]

Not doing Inform
But I also start with pen and paper to plan the story/puzzle/game. Especially the visual aspect or the gameplay (maze, puzzle, order of sequence), it helps organise my thoughts when I can see it drawn out. I’ll break the story in bullet points that I can cross out when I’ve written the section too.

When starting to code, I either add TODO comments in the file or have a separate .txt file where I track what I need to do, or fix, or etc… (often both…)

[HAL9000]

@BitterlyIndifferent

Thanks for sharing your research thus far. I especially liked Emily Short’s thoughts regarding the write the through-line first approach found near the end of her article. I find I have gravitated towards that methodology without addressing it as such.

Regarding my design process; 3 things have helped me immensely.

1. Scribbled notes and diagrams:
   Write a note with an idea, throw it in your pocket. At home, I have a pile of ideas that I then rewrite onto a sheet. The act of physically writing helps commit the ideas to the deeper part of my brain for further subconscious consideration. I have even got out of bed (before falling asleep), written another idea and then went back to bed. Inspiration can hit us at any time. Never let an idea slip through your grasp. Ever.

2. Mind mapping:
   I use Freeplane to map and connect point form ideas to organize characters, plot points, locations, themes, puzzles and then provide sub-points of their traits, plot impacts, location descriptions and items housed within, etc. I can collapse/expand entire branches of organized ideas so that I’m not scrolling through pages of linear word processor typed ideas. I see what I’m interested in and can safely not get distracted by other information. If it starts to feel like too much to juggle (or I’m not adding anything of importance anymore), I know I’m ready to start writing.

3. Through-line draft (and final draft):
   I write in LibreOffice, but turn on a dark interface and change the page background ground to a dark grey and keep my text colour almost white. This is how I prefer to play and present a game so as I type, it feels like the finished product, but I get the benefit of spell checking, etc. I also choose the font I wish to use in the game and use a page width to mimic the final story interface width to ensure I don’t leave widows, etc.

You can take all this with a grain of salt because I’ve yet to finish a game properly (I seem more preoccupied with learning engines and designing interfaces, than writing stories), but I have quite a few unfinished stories/ideas that are planned out very, very well. I swear!

EDIT: It’s important to note that this design process, and others described here, are typically an individual’s solitary effort to writing IF. In a team environment, other strategies must be implemented. When planning a story (or even commenting code) it’s important to note that there will ALWAYS be at least two readers of your design documents: you… and future you. Write it down for future you, and you should have sufficient documentation for if another person joins your project.

[inventor200 (Joey "Jess" Tanden)]

My process for IF is identical to my process for designing visual games. I have a text document that outlines how the game mechanics work, how it will progress, various brainstorming sections, etc, and then I have a spreadsheet for recalculating various values automatically to keep gameplay balanced while I tweak stuff.

[Lancelot (Onno Brouwer)]

I’ve got a bunch of notebooks around. Call me old fashioned, but I find that writing down ideas somehow makes it into my subconscious and often after I let them sink in for a while I wake up at ungodly hours, realise what was the thing I was struggling with, grab a notebook and write down what came to my mind. And then something emerges which gets me thinking maybe I can make a game out of this and start jotting down related concepts, maybe sketch a small map, and do the research on plot elements to try to make some coherent whole out of it which makes sense to me (and hopefully players as well). It can get quite messy at times…

Then I create little programs to test out game mechanics to make sure they can actually work, and try to get a skeletal game operational so I can get an idea for the flow of things. But it also really depends on what type of game one wants to go for I think. My first entry was a very linear affair and for that game it made more sense to me to create the story first, and then check how I could make the story actually work.

[SpecialAgent (Wesley Werner)]

I find this question fascinating, @BitterlyIndifferent thanks for posing it! I enjoy thinking about my process, and ways to make it easier. So I’m adding my method to the pot.

My motto is “keep it simple”. Because designing games is hard enough.

I keep a plain text file, if I have notes on paper, which I sometimes start with, I rewrite them into the file. I use the Markdown syntax and use a text editor (Geany) that detects chapter headings. That way I get a nice table of contents to navigate with.

Headings in my file:

• TODO
• Abbreviations, Symbols and Formatting
• Win conditions (single paragraph summaries)
• Sequence of events (detailed steps for each win condition)
• Room descriptions
• Character descriptions
  • appearance, notable traits, hobbies and sayings.
• Conversation topics
• Maps
• Story wording
  • preface, prose, win & lose wording
• Story features
  • custom verbs
  • feelies
  • hint system with its content
• References

Stay focused

Any ideas that pop into my head go under TODO, helps me stay focused. I review and expand them into the rest of the document at a later time, or the idea gets binned if I feel it falls in the realms of scope creep, not crucial, or bad ideas.

Top-down

I work on the summaries first: win conditions, then sequence of events, before I move on.

I don’t even worry about character names yet (I refer to NPC’s by their disposition or job - the baker, the mad scientist). If any conversation topics are required here, they are noted but I won’t write the wording yet.

This is the most crucial part of my design. Until I have described all the paths to win the story, I don’t consider it a viable game.

Details

Next I get stuck in the details of the world: room and character descriptions first, then conversation topics, maps, and story wording.

I note any researched items into the references section.

Done

When the document is near completion and I’m ready to start the code, I use pandoc to generate a beautifully formatted PDF which I use during implementation.

Of course there is always something to add or change. I consider them “living documents”. I keep using the TODO section to keep me focused, and update the design as needed. A shortcut in Geany allows me to rebuild the PDF at any time.

Example of the PDF table of contents

[SpecialAgent (Wesley Werner)]

@SomeOne2

On the “design side”, I write in paper, with scribbles that only I can understand (unfortunately), and arrows pointing off to pieces of text that are either massive, or tiny to fit inside/between the letters. I’m not even joking.

I have a similar shorthand on paper

[alyshkalia (Tabitha (ey/em or they/them))]

Wade mentioned Scrivener, which is what I use for organizing game notes, drafts, and game-related resources. This is some of the contents of my IF-focused Scrivener project—handy folders with notes on different engines, and then a folder for each game.

And an example of the contents of a game’s folder:

I need to be able to break up my notes and drafts like this, or else I just get lost. I struggle with the Inform IDE for this reason.

[BrettW]

For my first ever attempt at an IF game I did what I did for most projects: a whole of text files alongside the main code. This was a TADS 3 game. For example:

• Design rules
• Level plan
• Objects list
• A puzzle flow

Twenty years later, I got smarter and more organized and now… have a whole lot of text files. Specifically I’m one of those nerds with a Personal Knowledge Database, which is just a way to centralize the hundreds of design.txt I used to litter everywhere. I use org-roam in Emacs which gives me indices, tags and links between plain text documents. I also code up my games using Emacs, so it’s using the same tool for different parts of the project.

TADS 3 encourages multiple files for the actual code, so I typically separate the code by location, object or concept. I rarely put any design notes in the actual code because they will be lost.

I work alone on games, so these files are mostly collaborations with my past self, who is enthusiastic but wild. I don’t need to sell the plan to anyone, so my design docs are different to what you might use professionally.

The list of design documents tagged with Hand Me Down look like this:

The file titles are in the first column, and they are (inconsistently) tagged in the second column.

The bulk of the content is in Ideas for Hand Me Down which is an unordered list of random ideas like snippets of character or scene ideas, dialogue I might use, links to articles (mostly by Emily Short), or discussions about content.

Mansion layout in Hand Me Down uses a hierarchical document to lay out the main area. This was just on an area-by-area basis. If I got too prescriptive, then I should just be doing that in the actual code.

I had the puzzles separated in another file, based on a hierarchy induced by the game design.

For the finale (a mini Twine game), I had a file called Hand Me Down finale planner, which was an assortment of headings (Design Goals, Story arc, Design, Narrative tensions, Emotions, Endings, Character Values) with short notes underneath. By attacking it from different angles, I could see certain unifying ideas and gaps in the scene as I was developing it.

This is the style of design documents I would use for a sprawling, complicated game like Hand Me Down. I’m attempting a little game for Smoochie Jam 2024, and the design doc for that is a single file with a much more compressed structure. My next big project will probably be back at the design level of individual files for game flow, characters, and locations.

[gfaregan]

You could try creating a puzzle dependency chart or graph, and visualize it using graph creation software. If you’re smarter than me, you might even be able to figure out how to make a game with a complicated highly connected graph.