Technical writing with Scrivener

Earlier this summer, I completed a documentation project at the University of Warwick (my employer) for a web application called Tabula. The design and development teams rewrote the coursework management component, roughly a quarter of the app, from scratch. I was responsible for writing the support pages on the IT Services’ website for use by staff and students, and contributing to alpha testing.

The development team releases new versions of Tabula iteratively, typically once a week. I manage the documentation work for these releases using Atlassian JIRA, adding documentation sub-tasks beneath the developers’ parent JIRAs, which cover new features, bug fixes and improvements. The coursework management redesign, however, followed the waterfall methodology.

As a writer, this was a good opportunity to plan and write the documentation with free reign. None of the following usual constraints applied:

  • Merging new material with existing pages
  • Fitting new pages into an established information architecture
  • Locating and updating legacy screenshots

I was free to create the new support pages for coursework management in any structure and, on launch day, replace the live support pages in their entirety.

Planning the structure

Usually, at the start of a doc writing job, I practise using the app to learn the main processes, thinking as the user ‘how do I do x?’ If the feature in the app isn’t ready to try, then I follow the same thinking process using wireframes and mockups as the reference. I chunk these processes to arrive at a rough tree structure for the support pages and jot the structure in a spreadsheet. (Hat tip to the Project Managers at friends of ED; this simple method worked well on a whiteboard in the early 2000s for outlining text books and it works great today for web pages.)

Page titleSlugNotes1st draft ready2nd draft readyApprovedLive
Main process 1/process1
– Step 1/process1/step1
– Step 2/process1/step2
Main process 2/process2
– Step 1/process2/step1

For the Tabula project, I needed to start writing the support pages before much of the app was built and while UI (user interface) conversations were still in flux. While that’s normal, I wanted to try a new approach to writing the pages, specifically:

How can I write the first draft – and track progress – without being locked into an information architecture that is likely to change?

The main choice for the structure of the support pages was between the:

  • user’s role (student, administrator, marker, moderator, etc.)
  • task the user performs (submit an assignment, request an extension, and so on)

I wasn’t sure which approach was most appropriate but didn’t want the decision to hold up writing. I could have followed the draft structure in the spreadsheet and restructured it later.

  • Pros: can maintain oversight of progress and remaining pages to write
  • Cons: more time spent tweaking spreadsheets; less time writing

Another option was to create the draft structure in the University’s CMS (content management system) and write the first draft in the CMS.

  • Pros: easy to share work in progress with others for review
  • Cons: early investment in making a structure for approximately 50 pages, which may need to be reworked; when you need to quickly refer to other unpublished material, a CMS is an inefficient place to write in; difficult to track progress

Outlining with Scrivener

The Scrivener writing software is aimed at authors who write long-form content and books, with emphasis on publishing to e-book formats. According to their blurb, Scrivener “allows you to concentrate on composing and structuring long and difficult documents [and] its focus is on helping you get to the end of that awkward first draft.”

In Group Mode > Outliner, you can quickly create a draft tree structure. When UI conversations concluded with a decision on a particular feature or a new process was ready to test, I could drag and drop pages to new locations in the structure:

Outliner mode
Outliner mode in Scrivener. Click image to view larger size.

Outlining in this way particularly helped me to apply progressive disclosure techniques to the structure during the life of the project. The bulk of the support material (approximately 80%) is for an audience of administrators in the University’s teaching departments. Timeliness of support information is relevant, as is keeping unnecessary pages out of the way. For example, administrators set up assignments before term starts while marking assignments typically occurs towards the end of a term.

In Outliner mode, I added the following fields to help me keep track of pages I’d written and remaining work:

  • Labels: I used custom values to categorise each page by audience (student, marker, administrator, and so on).
  • Status: using custom values, I added progress terms similar to those in the spreadsheet column headings (to do, first draft ready, second draft ready).
  • Words: the word count of an individual page. My target was as few words as possible so this field helped to identify potentially bloated pages that could benefit from editing or splitting into several pages.
  • Total words: a useful cumulative word count of each section of the tree structure.

So, with the structure in place and a means to track progress, it was time to write.

Writing with Scrivener

Publishing and export options in Scrivener are mainly for word processor software or compiling to e-book formats. For web pages, however, I needed HTML to copy and paste into the University’s CMS. To add the capability to export HTML, I followed Thaddeus Hunt’s method to write in MultiMarkdown and compile to HTML.

With the tree structure and active page visible in the left-hand Binder, I wrote the individual pages in Markdown, jotting reference wireframe and JIRA URLs at the top of each page:

Writing in Scrivener in Markdown syntax
Writing in Scrivener in Markdown syntax. Click image to view larger size.

Being able to quickly refer to other pages and return to the page I was writing via the Binder was a huge time-saver.

Final steps

Once I’d written the second draft – final text without screenshots – I set up the tree structure in the CMS, pasted the HTML snippets into each page and then added:

  • Screenshots
  • Page metadata for search engines
  • Tag metadata for a ‘browse by role or task’ filter
  • View permissions for the appropriate audience

This is the point where the benefits of working in the CMS outweighed those of continuing in Scrivener to get the drafts ready for publishing. Also, by this stage, other web editors were helping to prepare the web pages, while stakeholders wanted an early sight of particular pages before publication. A CMS is ideal for this work.

Last thoughts

For large technical documentation jobs or long-form content where I’m the sole writer, I’ll definitely use Scrivener again. It helps me organise my thoughts, write swiftly and, most importantly, reduce overwhelm.

The visual design of progress indicators and customisable fields in Outliner mode are ideal for breaking a huge task into manageable chunks:

  • ‘Write 50 pages documenting all features of a new app that’s in development’ – crikey, where do I start?
  • ‘Write a page that explains how a marker can download the assignments they need to mark’ – yes, I can do that today

Also, for documenting web applications specifically, a writer needs to be adaptable. Features change. User-centred design is iterative. You may not be certain of how a process works or when an interface will be ready to test. That’s just how it is and you need to flow with it.

Having a flexible structure for the support pages that you can dip in and out of, and the ability to refine that structure when decisions are made and new features are available, is a great framework to give yourself the means to keep writing the first draft and avoid procrastination.

Be First to Comment

    Leave a Reply

    Your email address will not be published. Required fields are marked *