Editing and proofreading content with linters

A linter is a software utility that flags “suspicious usage” in software. Although linters are used by developers mostly to write more bug-free code, there are a few utilities emerging that work with documentation. They could be useful if you’re writing Web pages, markdown files or XML files.

Write good checks for passive voice, repeated words, adverbs, weasel words, wordy phrases and unnecessary words, and cliches.

Retext Mapbox Standard is a testing tool that checks for common grammar, sensitivity and simplicity errors.

Hemingway is an application, rather than a utility. You can paste your content into Hemingway for an assessment of its clarity. Hemingway will give your content a readability score and identify sections that are hard to read.

One to watch – Swagger2markup

Swagger2Markup promises to simplify the generation of REST API documentation by combining auto-generated API documentation produced by Swagger with manually written content. To include the programmatically generated snippets in your documentation, you’d use Asciidoc’s Include macro.

Swagger2Markup screenshot

The output would look like this:

Swagger2Markup output


What capabilities do Technical Authors want in an authoring tool?

We were contacted last week by a SaaS developer who wanted to know if their solution might be of interest to companies needing to write and host their product’s user manual or online Help content. So what capabilities do Technical Authors look for in an authoring tool?

There were a few features that sprung to mind:

  • Multi-channel publishing (for example: publishing to the Web, Microsoft Word and PDF). PDFs are still important as a publishing option, as people still like to read good quality printed content.
  • Separation of look and feel from content.
  • Content re-use (write once, re-use many times). This is different from simple cut-and-paste.
  • Variables (so it’s easy to change product names).
  • Conditional text (content that can vary depending on the type of user or type of product).
  • Link management (being able to find content in the project quickly, as well as being able to manage the dependencies among links and topics).
  • The ability to handle larger documents (200+ page documents with screenshots on most pages)
  • Expanding/collapsing table(s) of contents (and even different tables of contents for different types of users).
  • A user-friendly authoring environment.
  • Version management of the content.

Ideally, there would also be:

  • A way for occasional users to add and edit content without breaking formatting styles, using a User Interface that didn’t overwhelm them.
  • Access to and shared management of the content. This is so that writers could collaborate with each other, working on different topics for publications at the same time.

Are there any other features you would expect?

Not so cool tools for Technical Authors – speech recognition software

Our method for creating online courses involves making an audio recording of the presenter, transcribing it, editing the script and then recording the final, video presentation. We’ve tried using speech recognition software to create the transcribed script, and it has been a deeply frustrating experience.

While speech recognition is proving successful for searching and issuing commands (using Siri, Google Voice and Amazon Echo), we’re not sure it will replace the keyboard as the way we create written content.

Continue reading

Draftback – could it reveal how Technical Authors actually write?

James Somers is releasing an add-on for Google Docs, Draftback, that enables you to play back and analyse the creation of any Google Doc you have permission to edit.

It means you can see how a writer created the document, the sections they spent time rewriting and rearranging, the elements that were pasted into the document from elsewhere, and so on.

From an organisation’s perspective, the graphs Draftback that produces potentially could be used to show when and where the writer spent most of their time:

Timeline of activity

I could see this illustrating the impact of last minute changes to a product, review comments and other external factors. Potentially, it could also highlight areas where a writer might need assistance or training.

What do you think?

Your policy and procedures manual as software

Jared Spool tweeted this morning:

HyperCard was a hypertext program that came with Apple Macintosh in the 1980s. It allowed you to create “stacks” of online cards, which organsiations used to create some of the first online guides. It also contained a scripting language called HyperTalk that a non-programmer could easily learn. This meant HyperCard could do more than just display content: it could be used to create books, games (such as Myst), develop oil-spill models, and even dial the telephone.

Continue reading

SharePoint for documentation projects

Most of the Technical Authors I have met don’t have a good thing to say about Microsoft SharePoint. In many ways, it represents how not to publish content online. It is seen as encouraging people to move print-optimised documents (Blobs) around, rather than units of content (Chunks), and users are typically left to rely on search to find which document contains the information they are looking for.

For all those issues, SharePoint may still have its place – for managing documentation projects.

Continue reading

Issues for developers moving from on-premises software to Software as a Service.

On Monday, I spoke at the Visma Developer Days conference in Riga, Latvia, about some issues software companies have to address when migrating from developing on-premises software to Software as a Service.

One of the of the biggest changes is that the revenues are spread over the lifetime of customer – they pay on a monthly basis rather than an initial up-front payment. It becomes vital customers don’t give up on using the software after only a short while, because you won’t have earnt much income from that customer. If the software is difficult to use, and if users cannot find the answers to questions when they need them, there’s a good chance they will stop using the software, and stop paying their subscription fees.

We’re seeing a number of software companies changing their approach to providing user assistance (user documentation). More companies are thinking about it at the start of the project, so they can do a better job of delivering user documentation than they’ve done for on-premises software. They’re seeing documentation as part of the customer journey, and part of the design process.

This is welcome news, although it requires development teams to combine product design with information design. I wonder if there’ll be similar trends emerging at the next conference I’ll be attending – MadWorld 2014.