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.)

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:

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:

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.

After reading the introductory book to get an understanding of the user interface and workflow, my aim is to make motion graphics react to a musical source. Building on that, maybe I can use MIDI data as another input.

Here’s my first test export using a TOE file by Indae Hwang – the music is Summons from my Brinkmann Flag album:

I found the essays difficult to read on a desktop browser due to the site’s typography:

• Long line lengths spanning the full width of the browser
• Justified paragraphs rather than left-aligned (ragged right)
• Tight leading
• A serif font

When reading long-form articles online I prefer large sans-serif body text, constrained line lengths and leading between 1.3 and 1.5 ems. To improve the reading experience of the essays I made a custom stylesheet with new typography intended for use with the Stylish browser extension. I’ve shared the stylesheet via userstyles.org and GitHub.

Before

Credit: http://www.orwell.ru/library/essays/politics/english/e_polit – click image to view a larger version.

After

Credit: http://www.orwell.ru/library/essays/politics/english/e_polit with custom stylesheet – click image to view a larger version.

Install via userstyles.org directory

1. Add the Stylish extension to your browser. The extension is available for Chrome, Firefox, Safari and Opera.
2. Visit https://userstyles.org/styles/141074/.
3. Select Install with Stylish.
4. View any essay under http://www.orwell.ru/library/essays/.
5. The Stylish extension should prompt you that styles are available for the current site. Accept the prompt and add the styles.

Install manually

In Chrome the Stylish extension may not reliably prompt you that styles are available for the current site. Manually add the stylesheet as follows:

1. Click the browser extension icon and select Create new style.
2. Give the style a name.
3. In stylish.css copy all of the styles that are inside the @-moz-document and url-prefix rules.
4. Paste the styles in the Code 1 text field.
5. In the Applies to settings choose URLs starting with from the drop-down menu.
6. Enter http://www.orwell.ru/library/essays/ in the text field.
7. Select the Save button.

Work

In May 2015, the University of Warwick (my employer) launched its new brand designed by Frank, Bright & Abel. I’ve spent most of my time working with web editors, web developers, academics and marketing staff to update departmental websites to reflect the new brand.

My part involved:

• Guiding departments through site redesign projects
• Implementing responsive page layouts, particularly with Bootstrap
• Refactoring custom page layouts and functionality to take advantage of modern web standards
• Content migrations
• Information architecture planning and restructures
• Testing, quality assurance and launches
• Providing dedicated support for queries on the CMS, layouts, responsive design, SEO, navigation, graphic design, copy and launches
• Summarising digital branding decisions into a practical description of the University’s website template

The last of Warwick’s many (1,000+) websites moved to the new brand in September 2016, bringing a busy summer to a close before the start of a new academic year. It’s been an enjoyable, interesting and demanding two years.

There were two particularly enjoyable parts for me personally.

With Bootstrap and Font Awesome now rolled into the University’s template, I’ve been hand-coding designs again, creating responsive layouts with HTML, CSS and LESS. After several years in the WordPress domain, and shoehorning layouts into an inflexible CMS, it’s incredibly satisfying to make professional designs with clean, semantic markup. Doing so by hand, with a text editor and a browser, feels, um, ‘proper’ – a welcome return to a valuable craft. (I’m also lucky to be able to ask for help from a phenomenally capable in-house web team.)

Secondly, I now feel as if I know the University, and those who work there, better. It’s huge – a large town in reality. While the nature of the work has been digital, I’ve welcomed stronger relationships with people. I have a better understanding of the pressures other people face.

Home

My partner and I have refurbished our house. For three months in 2015, we lived upstairs – with two cats and a dog – while builders extended the ground floor. Blimey, that tested us! The building work is complete and the remaining decoration is down to us to finish.

Music

After two and half years playing guitar with Rhino & The Ranters, I decided to bow out at the end of 2015. That year was a blast with a real swell of support for the band. Highlights were performing at Lunar Festival in Warwickshire, opening for The Twang and The Wonder Stuff at Wolverhampton’s Wulfrun Hall, and contributing guitar parts to the Half Quixote EP.

Early in 2016, I challenged myself to learn digital recording and production. (My previous recording and live production experience is all analogue: tube amps, microphones and tape!) Since April, I’ve been learning Logic Pro X, sequencing, loops, software instruments and MIDI, amp simulators, compression and mixing. It’s fantastic to find software that I feel so at home in.

In parallel, I’m writing new music for an instrumental album tentatively titled Brinkmann Flag. It’s about a time- and space-jumping superhero with great hair, shoes and martial arts skills. When it’s time to release the album, the description will be much more serious and arty. Currently, I have eight tracks in the works. After sharing with close muso mates, I’m now focused on finessing the writing and arrangements. Here’s an early version of Spaghetti Northern:

Volunteering

Being honest, I’ve been lazy in sharing my time and skills with others. I will change this in 2017. The shock of the Brexit vote, and the non-shock of the subsequent government leadership vacuum filled by cruel Tory ideologues has given me a much-needed kick up the proverbial.

2016 has been a terrible year for many people and central government are making things worse through deliberate policy and ignorance. In my local neighbourhood and the wider city of Birmingham, the effects of the former coalition and current government’s austerity policies are in plain sight. Neighbourhood advice offices, children’s centres, social care provision, a police station open to the public, parking enforcement… these are either gone entirely or scaled back drastically.

Birmingham City Council was “forced to remove about £590 million from [its] budget as a direct result of unprecedented cuts in the amount of grant the Government has awarded Birmingham City Council. This equates to a 34 per cent reduction in grant since 2010.” They have also had to “reduce the number of staff working for the council by about 40 per cent.”

The vitriol of popular online culture and surfeit of misery in the mainstream press has caused me to tune out, particularly from Twitter, in 2016. I’m genuinely fearful for democratic and liberal values at home and around the world.

But, enough ranting! Time to go outside and do something useful. There are things I can do, even if they are small, to help others – and I will do stuff for Steph.

This year I’ve reconnected with the Kings Heath Residents’ Forum, supporting them with web content editing, WordPress maintenance and occasional social media updates. I could, and would like to, do more though.

Writing this post reminded me of the three company values of my former employer, Podnosh: “think; make a difference; give a fuck.” I needed a reminder and I think all three values stand up as good reasons to get better – at work, at home, in songwriting, in learning new technology, in volunteering, in talking with others and in helping my neighbourhood. Watch out 2017.

The trainer covered how to define your own ‘contexts’ or tags – common identifiers for tasks based on type, geographical location, relationships with other people, timeliness and energy level. He then described how to implement this system in Outlook and OneNote.

Thinking about how and where I work, and who with, I made the following tags:

@Agenda – manager

things I need to know about or ask for help with next time we meet

@Agenda – team

things to share or ask for help with

@Write/Make/Launch

deep concentration for hours without interruption

@Performance review

do these things before the next review

@Home

things I can do from home

@No brain required

easy jobs, like fixing broken links, when energy is low

@Projects

lengthy work I’m responsible for delivering

@Read/Review

University news, reports, blogs, RSS feeds

@Thinking

problem solving, analysing requirements, quoting

@Waiting for

need a response from someone else before I can go ahead

I then added four further tags for timing:

1-Now

Do this now

2-Next

Do these soon; likely to move to 1-Now within a few days

3-Later

Not urgent, just don’t forget them

4-Some day

Wish list

The at symbol and numbers prepended to contexts help to sort tasks in apps such as Outlook (via categories) and Evernote (via tags and shortcuts). Punctuation and numbers force tags to the top of lists sorted alphabetically.

Next, I made a list of essential features an app must have for me to use it in a GTD system:

• Create a task from an email easily
• Define your own custom tags
• Filter by custom tags
• Collaborative – projects or tasks are shareable
• Consistent experience across Windows 10, Mac OS, Android and iOS – I’m in the Apple world but work in an MS Exchange/Office 365 environment with many Windows/Android users

I’ve shared my notes on how Outlook, OneNote, Trello and Evernote performed, judged against the above five criteria in a Google Spreadsheet. All fared well except OneNote. Too much functionality for collaboration and tagging is missing in both web and Mac OS versions.

At work (the University of Warwick), I’m using:

• Outlook 2016 for Mac to manage email
• Outlook 2016 for Mac to keep track of tasks, using my list of custom tags as categories
• Trello for managing projects and collaboration

For personal use, I’m sticking with Evernote to keep track of tasks. I’ve used Evernote since 2010 as a notepad and scrapbook for ideas, and love how easy it is to capture and retrieve information.

So far, I haven’t made good use of tags though. After defining my custom tags for GTD in Evernote, following instructions on The Secret Weapon, I found the UI a little clunky. Nesting tags is pointless (they’re not exposed usefully in the UI) and I’m not a fan of the web version released in August 2015. The eye-strain-inducing expanses of white space, truncated note titles even on large screens, hidden functionality and sidebar navigation are a case of minimalist form over function.

Fortunately, you can revert the Evernote web app to the old version which more closely resembles the desktop app. Also, by dragging tags to shortcuts menu – and using shortcuts as the primary navigation – I found a clear, usable and consistent UI across desktop, web and iOS apps to browse and filter tasks by context, timeliness or both.

An important part of the GTD system, is the weekly review – checking what you’ve done, what you’re waiting on and what to do next. At work, I’ve settled into a routine of reviewing the list on Friday mornings. This gives me enough time during the rest of the day to finish anything I’ve forgotten about or pushed back during the week. At home, it’s Sunday morning with cake as a reward. The cake is a vital part of the system; without it, all effort is in vain.

I took photos in my local park while walking the dog. Each scene, viewed by eye, was a perfect English autumn composition. The resulting photos? Rubbish! Each image was underexposed, the rays of sunlight looked weak and the sky was a flat pastel. Not what I was hoping for!

I attempted to rescue an image with heavy editing using the Enlight app for iOS, my favourite photo editor. Digging deeper into Enlight’s mixer tools, I used the blending functions to combine two photos into the following woodland scene:

I’m chuffed with the result. It has a peaceful yet surreal feeling. While the trees, crocuses and earth are realistic, the rays of sunlight and purple accents at the right add a magical atmosphere.

Next, I played with a photo I took of Crosby beach (site of Sir Antony Gormley’s Another Place) with space imagery to make this double exposure:

To make the following image, I started with a double exposure from two of my own photos, Last of the light and Formby beach. Next, I wanted to place an aged structure that was unsettling and incongruous in a rural scene. The idea for this composition has been on my mind for a while; it’s inspired by Simon Stålenhag‘s digital painting in Tales from the Loop. The iron structure is a close-up of Zeche Zollern mine head tower (CC BY-NC 2.0) by Werner Wittersheim.

This image is shared on flickr (CC BY-NC-SA 2.0).

The lack of images is due to a missing og:image property in my post metadata.

The only information I found on how to populate this property, specifically in the Icarus theme for Hugo I use for my music blog, is by Brendan Quinn. He has shared his code used in Hugo’s internal partial templates to populate values for the Facebook Open Graph.

Most of Brendan’s code was over my head but I noticed the following line in his example post frontmatter:

+++
images = ["http://brendan-quinn.xyz/css/images/banners/responsive-images-landscape-seo.jpg"]
+++

I added the following line to my frontmatter:

---
images: ["/media/2016/07/20160721-little-walter-820x350.jpg"]
---

The republished post now contains two additional lines of metadata:

<meta property="og:image" content="http://twang.city/media/2016/07/20160721-little-walter-820x350.jpg" />
<meta name="twitter:image:src" content="http://twang.city/media/2016/07/20160721-little-walter-820x350.jpg"/>

The link preview now includes the defined image, which you can check with Facebook’s Sharing Debugger:

Similarly, checking the same URL with Twitter’s card validator shows the image displayed in the card preview:

Auto-Illustrator (no longer online at its original home swai.signwave.co.uk) has a GUI (graphical user interface) that mimics popular vector drawing applications. The software adds its own interpretation to the user’s drawing input, which makes for a random and playful experience.

So, I researched static site generators and settled on Hugo as a new platform to learn. Aside from learning a new technology, another reason for moving the blog to a static site generator is that my WordPress sites just seem so slow these days, despite optimising and aggressively caching where I can. Part of the reason is cheap shared hosting but, for personal sites, cheap hosting is fine with me!

Following a steep learning curve, I’ve migrated my music blog The Perfect Twang from WordPress to Hugo. This post summarises my learning so far. If you’re looking for a guide on moving from WordPress to Hugo, I recommend reading posts by Justin Israel and Justin Dunham.

Installation and set up

Installing Hugo on my Mac was the most difficult part of the migration. This is mainly due to my lack of skills with a command line and understanding of Mac permissions! While the Hugo installation instructions are short and clear, I hit permissions problems in Terminal immediately, which took some research to figure out.

Once I resolved these niggles, it was surprisingly easy to get a vanilla site up and running. Win! Next…

Content review

I used Ben Balter’s WordPress to Jekyll plugin to export my blog posts as markdown files, which contained tags, categories and other metadata. The export included a copy of the /wp-content folder, which contains images or other uploads related to posts and pages.

Reviewing the content is where I spent the bulk of my time. This involved:

• Fixing instances in post markdown files where symbols had become html entities. These were often apostrophes or quotation marks.
• Replacing absolute image paths, which contained WordPress’ /wp-content/uploads/etc, to relative paths to Hugo’s /static directory.
• Understanding where to store images and other content files referenced by posts. (There’s extensive discussion on GitHub.) I settled on recreating WordPress’ uploads structure of /year/month/myimage.jpg under my Hugo site’s /static/media directory.
• Understanding how to recreate WordPress’ permalink structure via Hugo’s config file settings to avoid having to implement any URL redirection or risk losing PageRank.

Theme and design

There’s plenty of themes available for Hugo sites. I chose the Icarus theme by Zhang Ruipeng and Digitalcraftsman for two reasons:

• You can include featured images with posts (known as ‘banners’ in Icarus).
• There’s a consistent-looking archives page that includes featured images.

I customised the theme with an override stylesheet to improve the following aspects:

• Contrast in the typography to meet WCAG level AA.
• Display of navigation on small screens, particularly at 400px wide.
• Display of post titles in archive pages on small screens.

There’s still work to do to make the site theme fully compliant with WCAG level AA but the major elements now pass.

Deploying

When the site is ready on your local computer, you type hugo in the command line to generate all the site files in the /public directory. This directory is then uploaded to the web server.

Whenever you write a new post, you need to regenerate the site and upload the entire directory of site files to your web server. My Perfect Twang blog of, to date, 20-something posts is 11mb when compiled in Hugo. Via my Virgin Media broadband connection to DreamHost, this takes about 20 mins to upload via FTP. Already, uploading by FTP has become a timesink, particularly when making small changes such as fixing a typo or publishing a new post.

So, next on my Hugo to-do list is to find a more efficient way to track and deploy changes to the live web server.

Performance

I’m very happy with Hugo in this area. With no queries or round trip to a database like WordPress requires (Hugo sites are simple, static html pages) there’s a significant improvement. The following table compares performance of the home page before and after the move to Hugo: