Thursday, January 18, 2018

It's in the Language We Choose

From https://www.minitool.com/backup/backup.html#backup-options, a backup software I was reading about:

Verify

By checking Verify Backup after Creation option, you can check the integrity of the backup immediately after the backup completes.

I would have wrote the following instead:

Verify Backup Integrity

Select the Verify Backup after Creation check box if you want to check the integrity of the backup immediately after the backup completes.

Here's my logic. First, the heading becomes the name of a task that starts with a verb. Second, I specify the name of the check box in the UI. Third, I don't use the same verb - check - to describe both the physical action of selecting a check box as well as what the program does when you select that check box. Fourth, I make it clear that this is an option to the user and not a required field by using the "if you want to" construction.

At work, i don't write text like this as I'm writing disaster recovery documentation, not software documentation. For all the reasons I loved writing software documentation, I love writing disaster recovery documentation more because I don't have to think about the many ways to write the text. I am merely assembling documentation that other teams write into a cohesive RoboHelp output.

No comments: