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.
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.
Select the Proofing Formats tab. By default, you will have one proofing format available, Paperthin.
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.
On the Proofing Formats tab, select Illume.
View Illume proofing copy
Open your story. Select the story name.
In the menu, select 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
Use Illume for reviews
To review, select a passage on the left under the Unreviewed heading.
If everything looks good, select Flag as Reviewed.
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.
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.
I have also written more posts about Twine.
- Twine Makes Branching Scenarios Easier (includes step-by-step directions on getting started in Twine)
- Color-Coded Branching Scenario Format
If you try using Illume, let me know about your experience. I’m interested to hear how others are using this option.