What Is Poof?

I’m a writer by trade. While I dabble in Twine, programming, and web development, writing is my job and, largely, my passion. For me, Twine is an attractive platform for development not just because of its relative simplicity, but also because of its focus on writing and its output to supremely shareable HTML files. But I think that Twine also has a problem, or blind spot at least, when it comes to a good writing, editing, and rewriting workflow. It’s just not all that easy to iterate on your prose the same way you can iterate on your design, mechanics, and code.

Maybe I’ve been spoiled by technology, but I want to be able to draft, fix, update, and draft more. I want to be able to work on my prose and mark it up with a pen, away from the harsh blue light of my computer screen. I want to be able to write notes about changes I want to make in between editing sessions. I want to be able to share my drafts with my friends for feedback, and get their comments and corrections.

So I made a proofing format called poof.

The Old Ways

I am involved pretty heavily in the Twine community, and most of the Twine authors I work with or help out know I’m a writer. They’re also often writers themselves. When I’m asked to critique one of their stories, they’re often looking for more than just impressions, and I want to give more, too. I want to be able to point to a sentence, word, phrase, and say, “hey, I tripped on this.”

What I typically do is hack the JavaScript a bit via the console to report to me the passage title on every new passage. It’s easier to do in SugarCube, but also possible in Harlowe. Then I open a Google doc, write the passage title in, copy and paste some problem text over, and make a comment in the Google doc, writing my thoughts there.

It’s laborious, boring. While in one sense it gives me a moment to think through my reaction, it also makes the process unappealing in general.

It was this dissatisfaction that first have rise to a desire for a proofing format designed to help me make my own critiquing / editing workflow simpler, faster, and more fun. Making a story format, though, isn’t really something you do in an evening, even for one as simple at its core as poof. But I assumed I could make one, if I was so inclined. Regardless, the idea, while there, wasn’t really formed.

The Problem of Paperthin

Paperthin is a format with a clever name and almost nothing happening under the hood. And that’s not a bad thing, per se. The amount of complexity required from a proofing format is directly correlated to what you expect it to do. Paperthin’s job is to put your passage text together into a single doc for viewing. Nothing more or less.

In my opinion, the critical flaw of Paperthin is the unwise (in my opinion) use of CSS pseudo-elements, specifically, the ::before pseudo-element. Paperthin renders each passage’s source code with a ::before holding the passage title. In CSS, pseudo-elements are not considered to be part of the document proper. They’re intended to be used as embellishments, icons, etc; things that don’t contribute to the document’s meaning or formatting. When you copy/paste or print the document, these pseudo-elements are omitted. By using these ::before pseudo-elements, Paperthin hamstrings its own usefulness. It becomes only a simple, readable copy that you can’t do anything else with.

So as an editing tool, importing a game into Twine a pulling up the proofing copy in Paperthin is less helpful overall than I feel it could be. And Paperthin has no JavaScript or commenting or editing, so as a format for critiquing or iterating on a draft, you’re just wasting time. It’s still easier to hack out the passage name in the console and use a Google doc for the heavy lifting.

Decompiling to Twee

There are many ways, including utility formats and third party compilers, to get a story into Twee notation, a plain text format designed for viewing and editing in a text editor. This is a useful feature, and one that wound up being included in poof, but more on my format later.

Many text editors come with spellcheck and other tools that can help you iterate on your prose, but I also think that as a critiquing or editing solution, there are some faults here, the biggest of them being the slowness of implementation.

Let’s talk about the other side of a critique or editing pass for a moment, the part where the original author (who may also be you) goes through the editing notes and weighs and implements the changes. Your editor (who, again, may also be you) just sent you a text dump of your story. Whether they’ve edited directly in the source or added notes, you now need to find every change or suggestion, review it, and decide what to do with it. You’ve been given a haystack full of needles.

While the editing pass was easy, the actual iteration becomes a slog. If you’re doing your own editing, this is less a problem, but only slightly, and that also assumes that your editing pass consists of fixes, not notes, to-do lists, etc. Mine usually consist of both, and I doubt I’m alone in that.

Any effective editing solution requires two major components. First, changes, notes, and edits must be easy to make; second, changes, notes, and edits must be easy to find, review, and implement.

Yeah, Sure, but Illume

Illume is a proofing format that allows authors to export their edits and changes as diffs, and is frankly an incredible solution. Poof is not really intended to be a replacement for Illume, as what Illume does is pretty great.

If you’re unfamiliar, you can use this link to install and check out Illume: https://www.maximumverbosity.net/twine/Illume/format.js.

Illume allows you to edit passages using a built-in editor, flag them as reviewed, and move on. You can export HTML files with your diffs, and use these files as a guide to your reviewing and editing process. Like poof, Illume also allows for a great deal of export options, and has ignore tags.

Whether you choose to use Illume or poof will likely come down to preference. I have nothing but nice things to say about Illume, but I did develop poof anyhow, and for three main reasons:

1. I think importable / exportable comments are a better solution for editing another author’s work. I think Illume is a superior format for iterating on your own prose, but I think being able to import comments from files makes it easier to work in larger teams, with more people, etc. This isn’t to say you can’t do this in Illume, only that I feel, personally, that being able to collect comments from multiple sources into a single poof view makes poof ideal for this specific use-case.
2. I think poof offers a different (though not necessarily better) toolset. While you can organize, find, and, filter passages with Illume, the focus of Illume is overwhelmingly on moving each passage from the “needs reviewed” list to the “reviewed” list. Poof has a similar filtering option; you can filter passages by whether they have comments or don’t, meaning after you’re done reviewing a passage, you can throw a comment on it that just says “done” or something, even if you don’t think the passage needs a change.
3. In a similar vein to both of these, I think poof is just less opinionated than Illume. It makes fewer assumptions about how you want to edit, who you are in relation to the project you’re editing, and how you want to spend your editing time. This means that poof has some benefits for some people compared to Illume, but also pales in comparison in other areas. Being less opinionated means that poof is less specialized and more generic.

What proofing format is right for you isn’t a call I can make, and while I think that Illume is incredible, I also designed poof because it more closely reflects my own desires and editing habits. If you edit like me–that it with notes and comments first, then rewrites, then more notes, then more rewrites, poof will probably fit your habits. If you prefer diving into edits right away, Illume will give you more bang for your buck. I think in either case, managing multiple comment sets is easier than managing multiple diff files, so I think if you’re working in a team, or sending your comments to another author, poof is worth trying.

Iterating on Prose

From this point on, we’re going to focus on poof, and some ways I think you can use it to help iterate on your prose. We’re not going to talk about Paperthin or Illume anymore; compare these proofing formats yourself and reach your own conclusions based on your needs.

Before we get too far ahead, let me clarify a term I’ve been using. They sound jargon-y, and I think I want to make sure we’re on the same page. So what do I mean by “iterating on your prose” anyway.

When I write, I waste no time concerning myself with quality on a first draft. To me, drafting is about words on a page, not perfection. It’s about the finish line, and generating something that can be refined later. Even if you don’t do this, your first draft will be garbage. It needs to be iterated on.

Iteration is the process of taking something, using it as a blueprint, and building something better with it. Your drafts are not your story, but a guide to what your story will ultimately become, through a process of editing, taking notes, and rewriting: iteration. Your prose will never be perfect. Instead, the process of iterating will become less effective until it is no longer worth the time.

This is how I approach writing, and how most of the writers I know do as well, though some to a lesser or greater extent. You don’t need to write like this to use poof or get something out of it, but I think it helps to understand my process to understand why poof is designed the way it is.

Comments

In poof, comments are the primary way you’ll interact with your prose. You can click the pencil icon to create a comment that contains all the passage text of the indicated passage to make edits, or create a new comment to leave notes, ideas, and suggestions. These comments are portable, meaning you can create a bunch of comments, then export a comment file to share with another poof-using person. This person can then import your comments into their poof view, and your comments will be added to any comments that are already there. This means you can use comments from a variety of collaborators, editors, or friends and see them all in one view, and delete them as you address them.

You can filter out passages that have or don’t have comments to help keep you on track. You can also search through and sort passages by a variety of metrics, so you can easily be playing a Twine game in one window, and commenting up those passages in poof in another, without having to hack the game to find the passage title: just filter by passage text.

Comments aren’t a perfect solution to everything: sometimes you just need a diff view like one powered by Illume, so you can create and export your edits. But as a general use way of taking note, recording reactions, and suggesting changes or edits, comments work pretty well, in my opinion.

Other Features

Finding and commenting on passages is probably the best use of poof, but a number of other useful features are included. Here’s a quick breakdown of what else you have at your fingertips:

• Export to PDF format to print and share. PDF format renders a very shareable copy of your passage content, and one that won’t look crappy if you want a physical copy to mark up with a pen.
• Export to Twee notation. As mentioned, poof can export to Twee, so you don’t need to get a format or compiler just for that.
• Export a Twine archive. Twine’s archive option archives all of your stories. You can use this option to generate a much, much smaller archive to create a backup of youor work.
• View modes. Poof comes with a variety of viewing options, including a simplified mode, a night mode, and more, all designed to help you get comfy and settle in for some reading.
• You can use a special passage to configure poof’s default settings, fonts, etc, and can tag certain passages to be ignores by poof.
• You can also view your JavaScript and CSS code with poof.

A Poof-Powered Editing Workflow

As a sort of sign-off, here’s some ideas I had while building poof. When you develop anything as complex as this, it helps to think about what you want and expect users to do with it. As I worked on poof, I thought about how I would want to use it, and how it could be used. Here’s a few examples of how you might build an editing or critiquing workflow using poof based on those design ideas.

Example 1:

You’re playing a game a fellow Twine author asked you to critique, and as you go you have comments, suggestions, and ideas. You import the game into your preferred compiler and open it in poof. As you play, you search for and find the passages you want with poof’s finding and filtering tools and make comments, then export the comment file and send it to the author.

Example 2:

You’re making a game with another dev, either as an editor or sharing the writing load, and need a quick way to share ideas and comments. You can “trade” comment files to see each other’s thoughts and make plans. While this is really no alternative to version control, opening issues on a repo is nowhere near as effective as a means for sharing writing ideas.

Example 3:

You want your non-Twine-using friend to give you feedback on your writing for a Twine game. Assuming they sufficiently understand the concepts of CYOA-style IF and passages, you could create a PDF export and send it to them. They can then import this file into Google Drive and create comments, or print it and mark it up.

The Future

Poof is still in a pre-release state, currently at version 0.3.2. This means poof isn’t done by a long shot. I considered adding diffs similar to Illume, but there’s little chance such an addition will ever be as fully-featured and well-designed as Illume: it will always be an after-thought at this point. While poof is largely feature-complete, there’s still a few bells and whistles and adjustments to be made, and if there’s something you want to see in a future version, raise an issue at the repo.

Note that poof isn’t going to do a complete 180 at this point. Future development on poof is unlikely to change the direction of the project, so if you’re not a fan or prefer another proofing format, there’s a pretty low chance that poof is going to set your world on fire in a later version. But I am open to hearing what you think it could do better anyhow, if you’ve got the time to talk.

Overall, I’m pretty pleased with how this project turned out, but there’s a lot of room for improvement, especially internally. Now that version 0.3.2 is up and most major bugs have been fixed and patched, I’ll probably be taking a week or two off before diving into the 0.4.0 verison, though I will certainly patch bugs if needed.