Illume Proofing Format for Twine

The Illume proofing format for Twine addresses 2 problems: reviewing and migrating content to other tools like Storyline.

The Illume proofing format for Twine addresses two challenges. First, it’s designed for collaboration, so others can review and provide feedback. Second, it can help you manage development if you need to migrate content from Twine to another development tool like Storyline. It’s not a perfect solution; I have a few improvements on my wish list. However, I have found that it saves me a significant amount of time with some of my projects.

What are proofing formats?

Twine controls how the story is displayed through two different types of formats: story formats and proofing formats. Think of formats like themes or design templates.

Story formats change how the published story appears (e.g., white background with black text or black background with white text). Different story formats have slightly different features, like a back button, or may handle images and tags differently.

Proofing formats are intended to help review stories, rather than being for end users. They can range from very simple, plain text exports to more complex options with additional features. Illume is a proofing format with additional features specifically to track changes.

Many different story and proofing formats are available for Twine, depending on your needs. I previously wrote about creating a color-coded flowchart for a story using the DotGraph proofing format.

Install Illume

If you haven’t installed Twine yet, check my directions for getting started with Twine. All screenshots in this post use Twine version 2.3.13 and Illume 1.0.5.

On the Twine start page, select Formats.

Twine screenshot. Install Illume step 1

Select the Proofing Formats tab. By default, you will have one proofing format available, Paperthin.

Twine screenshot. Install Illume step 2, proofing formats

Select the Add a New Format tab.

Paste this URL into the address field. Note the https (the Illume website says http, but that won’t work). Select Add.

https://www.maximumverbosity.net/twine/Illume/format.js
Twine screenshot. Install Illume step 3, add a new format

On the Proofing Formats tab, select Illume.

Twine screenshot. Install Illume step 4, select Illume

View Illume proofing copy

Open your story. Select the story name.

In the menu, select View Proofing Copy.

Twine screenshot. View proofing copy.

This will show you an “illuminated” copy of your story in your browser. As you can see in the image below, this has a number of sections.

  • Unreviewed: A list of passages (currently all unreviewed)
  • Passage Summary: Length and links for each passage
  • Stats: Number of passages, orphans, etc.
  • Summary: Total passages plus how many have been changed and reviewed
  • Reviewed: The bottom blue bar shows how much has been reviewed
Screenshot of illuminated story using Illume proofing format
Select the image to see the full size story overview.

Use Illume for reviews

To review, select a passage on the left under the Unreviewed heading.

If everything looks good, select Flag as Reviewed.

Screenshot of reviewing with Illume

To make changes, type the new text in the top box. The changes will appear with a tracked version below, and the passage will be marked with a C in the passage list.

Changes marked in Illume

When you finish changes on a passage, select Flag as Reviewed.

To review all changes, select View Change List. You can export the change list as an HTML file.

If you use Illume as a tool for collaborative reviewing, but your reviewer doesn’t have Twine installed, you can Export Illumination. This create an html file of the proofing copy with all of its interactive features. Your reviewers can export the change list. As the ID or developer, you can use the exported change list to make revisions in Twine.

Note that the changes in Illume are only saved in the change list. The revisions do not carry through to the original Twine story automatically. That’s great if you don’t want SMEs to break your stories, but annoying if you’re using it for revisions yourself.

Use Illume to help track development

Rather than using it for reviewing, I actually used Illume during my development process. I had a project with over 50 passages in Twine. Twine was great for writing and prototyping, but the final version needed to be built in Articulate Storyline.

If you’ve ever built a branching scenario, especially a larger one like that, you know how hard it is to keep track of which slides have been built, and which ones still need to be developed. In the past, I have used simple handwritten checklists to keep track. That’s OK for a smaller scenario (the client screening scenario has 17 passages), but not great for larger branching structures.

Therefore, I used Illume for myself. I treated “Flag as Reviewed” as meaning “Flag as Developed.” I just built each passage in order by the list and marked it “Reviewed” when I finished.

Working around Illume’s limitations

The one big challenge with using it this way is that Illume doesn’t save your notes about what has been reviewed and what hasn’t. It was great within a single development session, when I could just keep the file open and mark as I went along. But if I closed the file, the next day everything was reset back to the start again.

That’s because Illume pulls from the story file each time it opens. Unless changes are made in the story file, in Twine, nothing is reflected in Illume.

My workaround was to mark my spot each time I stopped working. In Illume, I noted the next passage in the list. Then, I went back to the story in Twine and added START HERE to the title of the next passage. That made it easy to find in the list. I could quickly mark everything above that start point as reviewed, and then continue development.

That’s not an ideal solution, of course. I’d love to have a way to save the current state of the illuminated copy, including what has been reviewed. Unfortunately, that isn’t currently possible with Illume.

Another option would be to mark the last passage reviewed as a change, and then export the change list. That wouldn’t require going back into Twine to edit the actual story file, so it might be a little faster.

Challenges for reviewing

The lack of an “in progress” save also makes it less useful for reviewing by other users. Unless your reviewers will complete their review in a single sitting, they could lose their work. I think it would be possible to use for reviewing with the right SME or stakeholder, but you’d have to train them. Most of the time, I will stick with exporting a plain text version of a story to edit in Word, rather than using something like Illume or another proofing format with clients.

I plan to keep working with Illume to see if I can improve that workflow, or if another proofing format might work better.

Further reading

You can see the full scenario shown here as a Twine prototype or in the final version in Storyline.

I have also written more posts about Twine.

If you try using Illume, let me know about your experience. I’m interested to hear how others are using this option.

2 thoughts on “Illume Proofing Format for Twine

Leave a Reply