Tag Archives: Software

Scrivener for Grant Writing

Scrivener is designed for assembling a long document from a large number of components.

Scrivener is designed for assembling a long document from a large number of components.

This post is about using Scrivener to write a grant application. I have wanted to write the post for a long time but I was held back by the fact that it is about an idea that, until last week-end, hadn’t come to fruition. The idea is that Scrivener is the ideal tool for writing a grant application.

Scrivener’s strength is that it is designed for the task of assembling short sections of text into a larger document and for editing and rearranging the segments until they work together. This is exactly the problem with a grant application. You have to assemble the background information about your research problem and the description of your research project and then edit and rearrange them until they work together as a coherent sales pitch for the project.

For the sales pitch to work, reading the background information about the research problem must make the reader want that research project and no other.  This requires the content of the background to be exactly tuned to the content of the project. This kind of fine tuning is much easier if you draft the corresponding subsections of the background and the description of the project,  which will end up several pages apart in the final document, side by side.

Scrivener was designed to do exactly this.  It is a program designed for writing novels. I discovered it through Twitter. Someone I follow, whose writing I admire, said they found it invaluable, so I wanted to find it invaluable too. But the sad truth is that I never have.  My problem is that Scrivener isn’t very easy to use. In fact it’s pretty difficult. Everything I have ever tried to do with Scrivener is much easier to do with a different program. Last week end, this changed.

Last week-end I had the grant-writing assignment from hell. I had four days to assemble a case for support. The raw material I had was patchy, to say the least. I had about 30 pages of text provided by eight academics scattered across four continents. 95% of the text was about research but the grant was about building research capacity. Important components of the research project were still being written, whereas the source of text on building capacity and capability had run dry. The least of my problems was that the grant was a kind I had never written before, requiring the case for support to have a unique structure and a limit of 10 pages.

The first thing I had to do – fortunately I had done this the week-end before – was to overcome Scrivener’s two great weaknesses.

  • It isn’t very good at producing Microsoft Word, which is pretty much the only medium in which the academics I work with can collaborate on a text.
  • Its approach to references and bibliographies is extremely limited.

I needed to find a way that I could convert Scrivener text into Microsoft Office, completely reliably and with very little effort. I needed to get Scrivener to interface with a good referencing software package so that I could combine the citations provided by all the different contributors into a single bibliography, in a compact format.

Fortunately I had discovered an excellent blog post  by David Smith explaining how to use a program called pandoc together with the excellent reference software Zotero to produce Microsoft word output from Scrivener. Pandoc converts a text file produced by Scrivener into a Word document, which uses styles defined in a document of your choice, and Zotero inserts and updates and formats citations and a bibliography, which has a style determined by a csl file, thousands of which are available on Zotero’s website.  I had never used Pandoc or Zotero, so it took me about a day and a half to become proficient enough with them to get the process working reliably. While I was getting pandoc to work I also found this csl file, which makes pandoc produce bibliograpies in the style of an obscure Italian law journal that does not require the titles of journal papers.

I was slightly apprehensive that Pandoc, which is a 1970’s style unix command-line application, requires you to type a monstrously long command into a terminal app. This is the command I used.

$ pandoc --filter pandoc-citeproc --reference-docx=/Users/amd/Dropbox/02Andrew/11-Scrivener/pandoc/reference.docx -s -S --normalize  -f markdown -t docx -o CaseForSupport.docx -i CaseForSupport

This command specifies the citation process, the path to the Word document with the correct styles, the format and the name of the input file,  that the output should be  a standalone file, that repeated white space should be stripped out of the input, the format to convert to and the name of the output file and the name of the input file. Other details, such as the datafile and format specification for the bibliography were specified in the input file but they could also have been specified in the command.  It takes a few tries to get the command right but once you have got it right you can repeat it whenever you need to by pressing the up-arrow  key.

Once I had taken care of its weaknesses, I could start exploiting Scrivener’s great strength, its facilities for assembling a large text document from a series of snippets of text that have to be organised in different ways. Text came to me as Word documents, which I converted to raw text, marked up with formatting instructions in ‘Pandoc-flavoured Multimarkdown’. These instructions are very simple, and they cover the bare minimum – six levels of heading, numbered and bullet lists, bold and italic –  so it only takes a few minutes to mark up a whole case for support and it is very easy to keep the mark-up consistent. It reminded me of writing my thesis in the 1970s, using runoff on a minicomputer, which was a machine the size of a wardrobe with 0.05 Mb of memory, 0.25 Mb of disk that cost £25,000 (£140,000 in today’s money).

Exchanging edits and comments with colleagues was easy. I would send them the draft case for support as a word file and they would send back the same file edited with track changes, send me comments, or send me more text. I had to convert their edited text back to raw text, mark it up, and put it into Scrivener. This was quick and easy because I kept each contribution as a separate file, and it avoided the formatting errors that frequently happen when you merge Microsoft Word files.

Adding references was very easy. As long as the writer could identify the paper I would be able to find it and add it to my Zotero database. This was easiest if the writer used the DOI or the Pubmed ID but in several cases I  succeeded with nothing more than a google search for the author names, year, and journal title.

The funder’s instructions for writing the case for support required seven different sections so I created a folder for each section and sub-divided the contributions from different writers between the sections. Scrivener makes it very easy to split a file at any point. You can also select text in the file to use as the filename. This makes it easy to create separate files for each little subsection and to give them names that tell you what is in them. By the time I finished editing the case for support it comprised about 30 files.

Scrivener's Corkboard makes it easy to rearrange the sections of a document.

Scrivener’s Corkboard makes it easy to rearrange the sections of a document.

Using separate files makes it very easy to reorganise the text if you decide the structure is wrong, as I did reluctantly when one of the contributors pointed out that the case for support looked as if the main point of the grant was research, whereas the funding call was for building research capacity and capability. Completely restructuring the case for support involved splitting one file into six or seven pieces to be distributed throughout the document and reorganising the other files so that I now had a two level structure, with folders and files. Scrivener has a very flexible view of folders and files, you can convert one into the other, but the advantage of a folder is that it allows you to move a group of subsections at the same time, without changing their relationships with each other, in a single drag and drop.  The whole restructure, which felt as if I was turning the case for support inside out, took me a couple of hours.

Without Scrivener I couldn’t have written the case for support before the deadline. Two features were crucial: the ease of restructuring, and the rock-solid reliability with which I could create a perfectly formatted Word file after every edit.

  • Restructuring a case for support in Word is possible: you can use the outliner to move subsections around, but it is very hard to keep track of what is where, and I have never tried anything as complicated as this.
  • Preserving the format of lists and the styles of headings through an exercise like this may be possible in Word, but I have never managed to do it. I spend huge amounts of time renumbering numbered lists and at least once in an exercise like this I will have to recreate all the heading styles from scratch.

Scrivener has a couple of other features that make it useful, but not uniquely so.

  • It allows you to assemble all the background information you need and keep it together with the text in a file called the project. You can do this by using the folder structure of the file system.
  • It allows you to tag files in different ways so that it can produce several different output files from the same project. I used this to produce other documents, like the pathways to impact, the summary and the objectives.

Finally, there is one thing I would like Scrivener to do that I haven’t yet managed to do. I would like it to insert boilerplate text several times in a document. Followers of this blog will know that I like to repeat myself and that I will re-use a key sentence several times. If I could do this by referring repeatedly to a single sentence, so that all the instances would change if I edited any of them, that would be perfect. Then I would be able to write a whole case for support by numbers!