Revise

How revision works in StoryShape

Open Revise from the footer tabs, or press Ctrl+5.

Revision is built from tasks. A task is something that needs work: a comment on a passage, a note about a whole scene, or a general job. Each task has an importance (Low, Medium or High), a category, and optionally a project pass, such as “Structure pass” or “Line edit”.

Any scene with an unresolved task appears in the Revision queue. Revise shows the original scene read only, so you can review without accidentally editing; make changes in Write.

Add scenes and comments

Comment on a passage

1. In Write, select the words you want to comment on.
2. Press Ctrl+Shift+R, choose Edit → Add Revision Comment…, or right-click and choose Add revision comment….
3. Type the Comment or task, choose a Priority and, if you like, a Revision pass and Additional notes.
4. Choose Add comment.

The exact passage stays attached to the comment, even if the scene changes later. If the passage is edited beyond recognition, the comment keeps its quote and says Needs relinking.

Queue a whole scene

• In Write, with nothing selected, press Ctrl+Shift+R, or right-click and choose Add scene to Revision list.
• Or right-click a scene in the library and choose Add scene to Revision list, or Add to Revision list and open markup to start marking it up.

Queuing a scene adds a “Review” task for it.

The revision queue

The Revision queue lists every scene with open tasks, with its book and chapter and how many tasks it has. Sort it by Manuscript order or Importance (the highest priority task in each scene).

Choose a scene to open its Scene review:

• Read aloud… (Windows), Snapshots… and Close scene are at the top.
• Scene tasks lists each task with its importance, status and notes. If it’s attached to a passage, choose View passage in… to open that exact text in Write.
• + New task for this scene adds a task with a title (“What needs work?”), Importance, Category, Project pass and notes.
• Edit task changes a task, and Move to Trash removes it.

Complete a task

Choose Complete · Pass N when a task is done. StoryShape marks it Resolved, saves a snapshot of the scene called “Revision Pass N”, and records the scene’s draft stage as that revision pass. Reopen task undoes it.

When a scene has no open tasks left, it leaves the queue. Its resolved tasks appear under Completed scene histories.

Browse every task

Filter and browse all tasks lists tasks across the project. Filter by Book, Chapter, Scene, Issues (Unresolved, Resolved or All), Project pass, Priority and Category. Clear filters shows everything again, and Open scene takes you to a task’s scene.

Mark up a scene

Markup is freehand ink over a scene, like a pen on a printout. It sits on top of the text and never changes the prose.

1. Open a scene in the revision queue. The SCENE MARKUP area shows the scene.
2. Choose a tool:
   • Read — look without drawing;
   • Pen — a fine line; with a pressure-sensitive pen, the line follows your pressure;
   • Highlight — a wide, translucent marker;
   • Erase — removes any whole stroke it touches.
3. Choose a colour: Red, Blue, Purple or Gold.
4. Choose Save markup.

Marks are tied to paragraphs. If the scene changes later, StoryShape tells you which marked paragraphs moved so you can check the ink still lines up. Marks it can’t place confidently are kept below under Unplaced original markup.

Markup from the iPad. Some markup made with Apple Pencil on Mac or iPad opens read-only on the desktop until it’s saved again on Mac or iPad.

Revision passes

A pass is a project-wide round of revision, such as “Structure pass”, “Continuity” or “Line edit”.

1. Open Project passes and all tasks.
2. Type a name in Name a project-wide revision pass and choose Create pass.
3. Assign tasks and comments to the pass as you add them.

Each pass shows how many of its tasks are resolved. Choose Mark complete when you’re done, or Reopen pass.

Give a pass a goal

Open Goals and reviewed scenes under a pass, then choose Edit goals…:

• Objective — what this pass is for.
• Scope — the whole project, a book, a chapter or a scene.
• Scenes to review, Chapters to review and Tasks to resolve — targets, or leave them empty to mean everything in scope.

Choose Save goals. Then tick each scene under Reviewed scenes as you finish it. If you edit a scene after marking it reviewed, it’s flagged Changed, and the pass says how many reviewed scenes have changed since review. Goals never complete a pass on their own.

Snapshots

A snapshot is a named, saved version of one scene. Take one before a big rewrite, and you can always compare or go back.

Open snapshots from Snapshots… in the scene review or the inspector, More tools → Scene snapshots… in Write, right-click in a scene and choose Scene snapshots…, or the command Browse saved versions / restore….

Save a snapshot

Type a name in Name this version…, such as “Before cutting the flashback”, and choose Save snapshot.

Compare

Choose a snapshot to compare it with the current scene. The comparison is word by word, and it says how many words were added and removed since.

• Changes shows additions and deletions inline.
• Side by side shows the saved and current versions next to each other.
• Individual changes lists each change as an Earlier and Current pair.

Restore

Restoring never loses anything. Before any restore, StoryShape saves the current scene as another snapshot, so you can always go back the other way.

• Restore this whole version… replaces the current scene with the snapshot. Choose Restore scene to confirm.
• Review restoring this change…, under Individual changes, brings back one changed passage. Choose where to Place it and whether to Keep saved passage formatting or Match current scene style, then choose Preserve current scene and restore passage.
• Restore selected passage… lets you select any text in the earlier version and choose exactly where it goes in the current scene.

Writing observations

Observations are counts and lengths to explore. They don’t score your writing or change it; they help you notice patterns.

1. Choose Writing observations… in Revise, or Workspace → Writing Observations….
2. Choose a Scope, and tick Include excluded scenes if you want them.
3. Choose Scan.
4. Choose what to look at under Observation:
   • Words — words you use often;
   • Phrases — repeated two- and three-word phrases;
   • Watch terms — how often your own watch words appear;
   • Sentence lengths — long sentences, at least 35 words by default;
   • Scene lengths — words and sentences per scene.
5. Use Filter terms or scenes to narrow the list. Choose a term to see every occurrence in context; choose an occurrence to open it in Write.

Ignore hides a term you don’t care about. If you edit the scope after scanning, StoryShape asks you to scan again.

Dictionary and watch terms

Choose Dictionary & watch terms… in Revise, or Workspace → Dictionary & Watch Terms…. The dialog is titled Dictionary & revision observations. Enter one item per line:

• Author dictionary — words that should never be flagged as misspelled in this project, such as invented names. No spaces.
• Watch words or phrases — words you overuse and want to keep an eye on, such as “suddenly” or “just”.
• Ignored observation terms — words observations should skip.

You can also set how often a word must appear to be reported (Report words and phrases used at least, default 2) and what counts as a long sentence (Long sentences have at least (words), default 35). Choose Save.

A revision routine that works. Snapshot the scene, read it through in Revise and leave comments, then rewrite in Write. Come back and complete each task as you go, and the pass keeps count. If a rewrite goes wrong, the snapshot is waiting.