Borkware Miniblog

June 14, 2011

Scrivener for long-form technical writing

Filed under: amosxp, meta, Random, writing — Mark Dalrymple @ 6:00 pm


Every now and then I come across a software tool that Gets It. A tool that does everything right. A tool that is a joy to use. VoodooPad is one. MarsEdit is another. Scrivener is the latest to enter the pantheon of My Favorite Apps.  The last three big chunks of new stuff for AMOSXP(3), (GCD, using Instruments, and a re-write and major updating of NSFileManager) were organized and written in Scrivener, and then later converted to DocBook for inclusion in the book. In all, about 18,000 words worth of work.

Scrivener is a non-linear text editing environment. Rather than having, say, a chapter of a book in one single Word or Pages document, you can have each section or sub-section of that chapter in an entity. You can organize these entities in an outline, and Scrivener will automatically flow the text as if it were a larger document. Each entity can be as long or as short as it needs to be.

For example, this is the “binder”, the outline view, for the new GCD chapter:

Dispatch binder

It has all of the sections of the chapter. If I’m wanting to edit the text for Dispatch Groups, I can select it in the Binder and focus in only on that text. If I wanted to make sure that the text flows into and out of that section, I can multi-select Time, Dispatch Groups, and Semaphores, and see those three sections of text in one editing panel, with subtle separators between the sections. If I decide that I really should talk about queues before terminology, I can just drag the entity and rearrange things. This feature alone, to me, is worth the low price of admission ($45).  Doing major surgery like that in a single document is fraught with peril.  With Scrivener, it’s drag and drop.  Don’t like it?  Undo it.

In addition to seeing the text, and a standard wordprocesor-style outline view (which I don’t use), there’s a cool corkboard mode. I originally thought it was silly and gratuitous, but I eventually found it to be a nice (and fun) way to play with the organization of the document. The corkboard mode also shows metadata, such as a high-level description of the section, its draft status, and other things:


You can see that most of the chapters are First Draft, meaning that I’ve gurgitated out the text, did an editing pass, and it’s ready to make the one-way trip to DocBookland for markup, professional editing, and indexing. A couple are “In Progress”, meaning they’re being worked on but not ready to see the light of day. I can tell at a glance what shape the chapter is in. You can rearrange the document here too. Clicking and dragging the note cards is reflected in the outline view, and hence in your overall body of text.

One of the cool things is the text contents of the note cards. The title of the card matches the title in the Binder view. Simple enough. But you can also have a description, independent from the actual contents of the section. Scrivener gives you a lot of opportunity for out-of-band data. With traditional word processing environments, pretty much everything that’s in the document is part of the flow of text, except maybe things like reviewer’s comments. Scrivener has lots of opportunities for attaching meaningful metadata to sections: add tags, arbitrary keywords, arbitrary long notes and descriptions. Fiction writers can tag scenes with characters, themes, locations, smells, etc. Later on they can do searches to see all the scenes a particular character is in, or what sections concentrate on badger foreshadowing.  I didn’t use much metadata stuff, mainly the note card descriptions and the status.

In addition to the “Draft” area, which has all the text of your document in the little entity files, you can have any number of non-publishing hierarchies of stuff. I do most of my research in VoodooPad – it’s where all the raw information goes as I read technical docs, research on the web, and write test apps. Then I bring it over piecemeal into Scrivener as I suss out how things should be organized, and figure out what needs to be included and what can be left on the floor. Here’s the research part for Instruments:


Each of the texty-looking icons is the equivalent of a text file. You can have whatever text you want there, formatted how you want, embedded images, etc. Kind of like Keynote, these text docs aren’t the leaves of the tree. They’re also the internal nodes. The “Different Kinds of Instruments” text doc actually has three child documents too, each with their own text. I can select “Different Kinds of Templates”, and see its text, along with the children’s text in-line (if I want). There are also images, in this case screenshots, that are part of the “document” hierarchy. As I was writing the chapter, I’d be migrating important information from Voodoo Pad, arranging and rearranging entities so the order of presentation made sense. I wrote a fair amount of the chapter’s prose here. As I took screen shots, I added them as child nodes to the text they would appear in. This way they’d carried along as I rearranged chapters. It’s a very powerful, yet easy to use system.

One odd thing about Scrivener is that it is actually fun to write in. No other text editor feels as responsive as Scriv’s. It’s hard to describe, but typing just feels better than in other apps. The obligatory full-screen mode is nice when you have to concentrate to Get Things Done.  Also, I am a huge fan of the “typewriter” mode. This centers the line being edited in the window. I can have a tall window so I can get lots of context, but when I’m actually typing and editing, the text is in the sweet-spot of my eyeglasses.

Indie developers would should take a good look at Scrivener’s website.  I spent a long time reading the materials, and looking at the demo movies.  They’re all very targeted.  “Here is a cool feature, here’s how it fits in with the rest of the product and here is how you would use it.”  After awhile, I got a very good sense of the how the product worked, and what particular features would make my life easier.  I had zero problems getting Real Work done immediately after download.

So, if you’re into any kind of long-form writing, whether it be novels for NaNoWriMo or technical books, or even the occasional complicated blog post, I recommend you check out Scrivener. It does so much Right that it is a joy to use.

Leave a Comment »

No comments yet.

RSS feed for comments on this post.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a free website or blog at

%d bloggers like this: