This summer I completed a documentation project for Tabula, a web application developed in-house by the University of Warwick’s Web Team. Tabula is the Web Team’s busiest web application regarding support. It’s used mainly by departmental administrators to:
- manage coursework assignments, including routing students’ work through workflows for marking and moderation
- schedule small group teaching events such as tutorials and lab classes, and allocate students and tutors to those events
- monitor students’ attendance
The Tabula development team redesigned the coursework management component, roughly a quarter of the app, from scratch in 2017. I was responsible for designing and writing an online manual for an audience of departmental administrators, students, markers and IT support colleagues. The brief was to:
- document every feature
- write tutorials on how to complete coursework management tasks using the app
- mark up web pages for faceted filtering by role or task
The development team releases new versions of Tabula iteratively, typically once a week. I manage the documentation for these releases using Jira, adding sub-tasks beneath the developers’ parent JIRAs, which cover new features, bug fixes and improvements.
The coursework management redesign, however, followed the waterfall methodology. For a technical writer, this was an excellent opportunity to plan and write the manual with free reign. None of the usual constraints applied, such as:
- merging new material with existing pages
- fitting new pages into an established information architecture
- updating legacy screenshots
I was free to create the new web pages for coursework management in any structure and, on launch day, replace the live pages in their entirety.
Planning the structure
At the start of a technical writing job, I usually practise using the app to learn the processes and put myself in the user’s shoes, thinking ‘how do I do x?’ If a feature is not available to experiment with on a test site, I follow the same thinking process using wireframes or mockups as the reference.
I chunk the processes into a rough tree structure of web pages and, wherever possible, get feedback on the structure. For this project, I carried out a quick online card sort exercise using OptimalSort.
Next, I jotted the structure in a spreadsheet, then wrote plain English URL slugs and tacked on my usual columns to track progress. (Hat tip to the project managers I worked with at friends of ED. This simple method worked well on a whiteboard in the early 2000s to outline textbooks, and it works well today for website architectures.)
|Page title||Slug||1st draft||2nd draft||Approved||Live|
|- Part 1||/process1/part1|
|- Part 2||/process1/part2|
|- Part 1||/process2/part1|
For Tabula, I needed to start writing the manual before much of the app was built and while user interface conversations remained in flux. While that’s normal, I wanted to try a new approach to writing the pages. How could I write the first draft, and track progress, without being locked into an information architecture that’s likely to change?
The primary choice for the manual structure was between:
- the user’s role (student, administrator, marker, moderator)
- the task the user performs (for example, submit an assignment)
There was no consensus from the card sort exercise, so I was still unsure of the most appropriate approach to take. I did not want the decision to hold up writing though.
Build or write
One option was to start writing pages, track progress in the spreadsheet and adjust the draft structure later:
- Advantages: useful to keep oversight of progress and remaining pages to write
- Disadvantages: time spent maintaining spreadsheets means less time writing
Another option was to build the draft structure in SiteBuilder, the University’s CMS (content management system), and write the first draft in the CMS:
- Advantages: easy to share work in progress with others for review
- Disadvantages: early investment in building a structure of approximately 50 pages, which may need reworking down the line; when you need to refer to other unpublished material quickly, a CMS is an inefficient place to write; challenging to track progress
Instead, I chose to use a dedicated writing tool that has outlining features.
Outlining with Scrivener
Scrivener writing software is for authors of 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.”
I used Group Mode > Outliner to create the manual’s tree structure. When UI conversations concluded with a decision on a particular feature or a new process was ready to test, I updated my structure by dragging and dropping pages.
Outlining this way helped me to apply progressive disclosure techniques to the manual’s table of contents. The bulk of the manual, approximately 80%, is for an audience of administrators in the University’s teaching departments. Timeliness of support information is relevant, as is keeping unneeded pages out of the way. For example, administrators set up assignments and small group classes before term starts while marking assignments typically occurs towards the end of a term.
In Outliner mode, I added the following fields to track pages I’d written and the remaining work:
- Label: custom values to categorise each page by audience
- Status: custom values to show progress (to do, first draft ready, second draft ready)
- Words: the word count of an individual page; my target was as few words as possible to convey the information, so this field helped to identify bloat or a page that would benefit from breaking up into several pages
- Total words: the cumulative word count of each section of the tree structure
With the structure and a means to track progress in place, it was time to write.
Writing in Markdown
The publishing and export options in Scrivener are mainly for word processing software or e-book formats. For the manual, however, I needed HTML to paste into the University’s CMS. I followed Thaddeus Hunt’s method to write in MultiMarkdown and compile to HTML.
With the structure and active page visible in the Binder at the left, I wrote each page in Markdown, jotting wireframe and JIRA URLs at the top of each page along the way:
Being able to refer to other pages and return to the page I was writing via the Binder saved valuable time.
Into the CMS
Once I’d written the second draft, the final text without screenshots, I built the tree structure in the CMS, pasted the HTML snippets into each page, then added:
- metadata for search engine indexing
- metadata for the role and task faceted filters
- view permissions for the appropriate audience
By now the benefits of working in the CMS outweighed those of continuing in Scrivener to prepare the drafts for publishing. Also, at this stage, other writers were contributing pages, while stakeholders wanted an early sight of particular pages before publication. A CMS is ideal for this work.
For sizeable technical documentation jobs or long-form content where I’m the sole writer, I’ll 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 Scrivener’s Outliner mode are ideal for breaking a massive task into manageable chunks:
- write 50 pages documenting all the features of a new app in development – crikey, where do you start?
- write a page to show a marker how they can download the assignments they need to mark – that’s a self-contained task you can start now
Also, for documenting web applications specifically, a writer needs to be adaptable. Features change as does the speed at which they change. User-centred design is iterative. You may not be sure of how a process works or when an interface is ready to test. That’s just how it is, and you need to flow with it.
Having a flexible structure for the support pages, and the ability to refine that structure as decisions and new features become clear, is an excellent framework in which to writing the first draft and avoid procrastination.