How do you all handle design documents?

Hello! I’m new to the IF writing scene, and I’m putting together a resource to keep on target for my first game. So far, I have a section for supporting lore and a description to help inform the voice of the player-character, with the intention of adding a streamlined plot synopsis next, and then notes for pacing and maybe ideas for puzzles that fit with the narrative.

I’ve never done this before, so it would be helpful to compare notes! What goes into your preparations for a new game?


First you have to write your own IF engine.

I’m joking, I’m joking. OK, I’ll leave. :wink:

Don’t mean to dismiss your question, which is an interesting one. I’m sure people will chime in soon :+1:

1 Like

I start with an idea, then write the start and the end. After that i design the story, the characters you meet and the challenges. I put this into a single working document that starts to take shape. I write the chapters and plan the associated artwork. then i code it.
Oh, and @tundish, i’ve already written the IF engine :slight_smile:


I’m just a duffer here.

Scrivener to keep track of potential story ideas, characters, items and everything else.

Trizbort for mapping. I don’t use it to export any code, just to keep a diagram of the room relationships.

TADS 3 is my authoring system of choice. Inform 6 and its standard library and Punyinform as an excellent alternative.


I do not keep any documents in any organized fashion, unless you count random notes scribbled on receipts, book margins, and torn bits of paper as “design documents.”

I just sit down and write it, and sometimes the little scraps of paper with notes are useful, but often not.


@fos1 I tried to get into Scrivener. it looked good, but it doesn’t like markdown. I tend to do everything in markdown now as it’s quick. Ive been using Obsidian to do this.


@fos1 I didn’t know about either of these resources! I think Scrivener might be overkill for any of my use cases, but I’ll remember Trizbort if I start a more ambitious project. I don’t plan on implementing more than a dozen rooms or so for this one, so it’s easy enough to conceptualize for now :smile:

1 Like

I have used markdown with with web pages that have a flat file format.

I will have to take a look at Obsidian.

Once I learned Scrivener several years ago, I began using it for writing projects at both work and grad school. I no longer do either but I still enjoy Scrivener. :wink:

1 Like

I think the best approach here is really going to depend on your tools and the kind of game you’re writing, but for my part I’ve tended to write up general notes that break down the overall act structure (which for a parser game, often corresponds to the geography), puzzle concepts, plus snatches of dialogue or descriptive details that I want to get across once I get into implementation – basically getting enough down to know where each chunk of game is headed and how the whole piece fits together, without duplicating too much effort when it comes time to move to coding.

If it’s helpful, I linked to the final version of my design doc in the post-mortem I wrote for my first game – you can download it if you scroll all the way to the bottom of this post.


I’m a duffer as well, but +1 to Trizbort for designing maps. I only start using it after I’ve jelled out how I want the map to look in general, not at the beginning of the project.

The reason I like Trizbort (although you could use anything, including paper and pencil) is that I find myself getting mixed up direction-wise if I don’t, flipping east-west and north-south. I don’t know why this happens. It is just me?

I need some kind of to-do system for any creative project. For traditional fiction, I use my phone & computer’s notes app; for IF, I use GitHub’s issue tracker. I still keep a paper notebook handy for jotting down ideas.

Generally, I find I need organization, but not too much organization.


@DeusIrae Thanks for posting your design notes. Mine go into a lot more detail than this. I realise this is because I’m a weak writer and need more planning. I think a stronger writer can just take a sketch set of notes and run with it. Horses for courses, i guess.

I’m working on some new material at the moment and my new approach is to ask myself, “how is this bit telling a story?” That means most puzzles are out, and in are background cameos and subplots.


I think this is a really important question to ask while writing. Sometimes you have to kill your darlings, and cut a cool puzzle that just doesn’t fit, or toss out the character you love that isn’t furthering the story you’re telling.

That said, many of my favorite games have wafer-thin stories, and the puzzles/mechanic/PC/map are just so awesome that I don’t care that the story is weak. I love story-heavy games, but sometimes you just want to play.


Honestly I think it’s mostly practice and what you’re used to. I forget if I mentioned this in the postmortem thread, but while this was my first piece of IF, I’d previously run a whole lot of tabletop role playing games, and as a result had lots of practice figuring out what kinds of notes, with what level of detail, I needed to have prepped ahead of time to enable me to run a scene and improvise as needed. So I took a similar approach when I was planning the game, with the design-doc phase analogous to prepping and the implementation phase analogous to running things.

Actually a pair of WIP of mine are lore-heavy, because I’m actively expoloring the concept of “knowledge and lore as treasures” in a modernisation of the ancient “treasure hunt” genre of IF, so I guess that I’m symphatethic with catiua.

I embed my design documents inside the code, in the form of rather long comments (coding sense), and indeed in the I7 context I’m mulling about exploiting the usage of the heading for better organising and encapsulating (coding sense) the design notes.

Best regards from Italy,
dott. Piergiorgio.

1 Like

@DeusIrae Thanks for sharing! I can see how much work you put into your puzzles, and I think it will help me manage expectations for my own.

If context helps, my game will be written in Inform7, a dark fantasy in three acts. I believe my biggest challenge will be the NPC-heavy first act, which (as it stands now) will start in media res with a good deal of exposition to cram in for a player-character already established in the setting. Definitely not something I can write by the seat of my pants, hence the need for planning.


I don’t do a great deal of planning. The three things I need to know before I start are the setting, the game mechanic, and finally who the player character is and what they want. If I don’t know any one of those things, the game usually fizzles out and goes nowhere.

If I have a good idea of those elements, I just start, but I’ll usually do a lot of research as I go. If a game has a historical setting, I’ll research that setting and sometimes a small detail will suggest an object, a puzzle, a scene or a character. I like to create on the fly; if I planned everything out at the start writing and coding would soon become a chore.

I used to keep notebooks, but now I use Google Keep Notes on my phone and jot ideas down as they occur to me. Much like dott. Piergiorgio, I transfer these notes into the code as comments to keep them all together.

The exception to this is the map. I normally draw maps on paper, and they usually evolve with the story. I sometimes redraw the map three or four times before it “feels right”. I’ve tried using Trizbort, but I don’t find it any faster than pencil and paper. It’s excellent for creating polished looking final map though.

It’s a good idea to know what your ending (or endings) will be fairly early on in the process, and create a through-line (make it solvable from beginning to end) as early as possible. I have to confess that I seldom do this. Production goes a lot more smoothly when I do.

I usually have three or four games on the go at any one time. If I get stuck with one, I’ll jump onto one of the others for a while. Games that are obviously going nowhere sometimes get cannibalised for parts.

Sometimes you have to “kill your darlings”. If a beloved idea doesn’t fit the game it’s part of, it can hold the whole project up. When that happens, I take it out and put it aside for future use. An orphaned idea for a puzzle can hang around for years before it finds the right project.


This is something I would like to see. Will they be available in English?

1 Like

well, isn’t the specific case, but some WIP of mine started well prior of the first announcement of Final Fantasy Versus XIII… I have taken as this year’s resolve being less reserved about my WIP, but with many WIP started even in the late 90s-early 2000s, I prefer avoiding too many expectances…

oh, well… today in the light of this very debate, I have started the restructuring with I7’s heading structure the notes inside the oldest of all my WIP, Trial of a Witch, started around 1994 with Advsys, later ported to inform 5.4, 5.5, 6 and now 7.

This day’s work rough 20% of the editing work, whose is a very fine example of organising (thanks to I7’s heading system) documenting & annotating inside the code, the very first time I actually give an anticipation:

"Trial of a Witch (not the classic meaning...)" by "PGdE"

[heading memo: volume-book-part-chapter-section]

volume 0 - general notes

book 0 - core notes

part 1 - the world

[Earth, 28th Century, starships roams the inner space, and magick roams the Earth and his colonies in the solar system, (think Star Ocean) and the world after the "Magick revolution" is changed more than the past industrial and computer revolution] 

part 2 - the setting

[Earth, the ancestral and storied mansion of the extended Witch family, four floors (EU count: ground, 1st, 2nd, 3rd) plus attic, underground floor, terraces, balconies, a sizeable garden, perhaps even a dependance, surely there will be my staples, an arosnook and an outhouse]

part 3 - the lore

[The Magick Revolution was a sort of slow-paced shadowrun, in the course of decades instead of few years]

[The magic-users are termed "Witchblooded"; they're practically all female (7/8; let's say that they have a different mitosis (or is meiosis ?) process, giving a 7:1 F/M ratio instead of the 1:1 ratio, and on top of it, the offspring of a witchblooded is always withblooded]

book 1 - plot

[in a nut: pass the trial, by dispelling the wards blocking the progression, on the different floors and outside; tentatively, a ward for the top (3rd and 2nd F), two for the 1st floor, more than two (separately) for the ground floor and the garden, main puzzles of increased difficulty proceeding down and outside for a dozen or so of wards; Following Lord Nelson, the top floor is the opening, the 2nd and 1st floor the early middle game, and the ground, inside and outside, the late middle game; the end-game will be a final test involving the entire map and all the PC has learned/gained in solving how to dispel the wards; of course by the late middle game, there will be teleports for player's QoL...]


book 2 - characters

part 0 - general

[this IF work, by its nature has "abandonitis", but as part of her trial, she can trasmogriph into some of her relatives (with certain limits), borrowing their physical and/or magick traits, so, the player character is one, but the actors character are more than one (no more than two or three]

part 1- player character


[appareance: see the desc;] 

[status: she's the eldest of the trainees in the extended family, so it's her turn to get her initiation..]

part 2 - denizens of top floor


Volume 1 - setup, general routines &c

absolutely NO IDEA of if and when will at least reach ß state… with luck, mid-20s, I wild guess.

Best regards from Italy,
dott. Piergiorgio.

You might find these interesting:

(Links to these and other articles about the craft of writing IF can be found at IFWiki’s Craft page.)