Plain language with long required phrases

Question

I am trying to create documentation for an application, and it's for end users who use keyboard (not mouse) and a screen reader.

Some of our conventions require us to always use the full phrase as listed on screen: if we're talking about the category combo box, but the label says "Please pick a Category:" [sic], that's what we have to use.

Another convention is for keyboard shortcuts -- they are always several "words" long, as we use white space (or I go non-breaking-space) between each element of it. So we have CTRL + INSERT + T for tables list.

So as you may have noticed, I have a tendency towards long sentences with many clauses. I'm using Hemingway to check each section for Plain Language, and I'm trying to revise the hard/very hard sentences.

The problem is, my sentences are often very long and it's not my fault!

If I replace a multi-word phrase whether keyboard shortcut or on-screen label with "xx," that usually brings the sentence's word count down that the sentences "pass."

Is this "cheating?" Are these "terms of art" and it's ok to say "Ctrl + INSert + number pad 6" is understood as a "word?"

Should only the keyboard shortcuts count as 1-word, as the users may know them from other uses of the screenreader, (so replacing them mentally with "X" for a plainLang check is ok), but "envelope Send Email checkbox" still has to count as 4 words, as they would be new to the user? Or only the first-usage within a section?

Note: My workplace doesn't allow the use of 2nd person, despite PlainLang encouraging personal pronouns -- I'm already "wasting" words by having to always say "the user" instead of "you."

I'd like to know if other technical writers have a consensus on how to handle these conflicts.

Answer 1

It's possible you're tying yourself in knots with Hemingway which is, perhaps, better for prose writers than technical writers.

Hemingway themselves state:

But what if I want to break the rules?

Rules are meant to be broken. If you know what you're doing, don't let us stop you. View our suggestions as just that.

I used to write instructional manuals for IBM and Sun Microsystems. For new users, I'd try to emulate the formatting of a Dummies book. Word 2007 for Dummies has a Look Inside for you to see how they handle it.

If you aren't constrained by company formatting, try splitting out the processes with a quick explanation, followed by a numbered list of commands, with the clicks and keyboard strokes in bold, and explanations unbolded. Like this:

IMPORTING A PICTURE INTO A MS WORD DOCUMENT

Importing pictures into Word is very easy, just take the following steps:

1. Left click the INSERT menu option. A pop up menu appears.

2. From the pop up menu, select PICTURES. A side menu appears.

3. From the side menu, select PICTURE FROM FILE.

Stripping each method into numbered lists avoids long, complex sentences with commands embedded in the middle. Of short sentences like this, Hemingway should approve.

I've used mouse clicks in this example, which you would just switch out for keyboard commands. I didn't know the keyboard commands for this example!

HTH, but difficult to advise better when I don't know all the rules you have to abide by.