8

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.

  • Lot's of questions here… Is it possible to use inferred 2nd person, where "you/the user" is just skipped? – wetcircuit Apr 4 at 14:12
  • Yes, I do use a lot of that. "Press insert+f5, navigate with down arrows to the most accurate option, then press enter to activate it." – April --Un-Slander Monica-- Apr 4 at 14:42
  • yeesh, that is a long sentence… And this is necessary every time? – wetcircuit Apr 4 at 15:18
  • You might try tricking the software by replacing the spaces in those phrases with some special character you don't normally use; like '^', which you can do a global replace on later with a space (or non-breaking space). So "CTRL^+^INSERT^+^T", and maybe Hemingway will count it as a single word. – Amadeus-Reinstate-Monica Apr 4 at 15:39
  • 1
    I wonder if there are conventions specific to screen-readers that should factor into this. This question would benefit from input from somebody who regularly uses a screen-reader. – Monica Cellio Apr 4 at 15:39
8

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.

  • No pictures -- these users are visually impaired. Things are already numbered and as short as I can make them. – April --Un-Slander Monica-- Apr 4 at 19:17
  • 1
    Then is it possible you've already done a great job and Hemingway is making you doubt your own skills? – GGx - Reinstate Monica Cellio Apr 4 at 19:19
  • 1
    It may be. I haven't done a tech document before (though I've taught tech writing), and I've never had so much time to proofread/edit the heck out of something. As an instructor, it was write&go (assignment sheets) , or give a few tips in student feedback. We don't have much collaboration in this office, which is partly what I was hoping for. – April --Un-Slander Monica-- Apr 4 at 19:24
  • @April is there really no-one in your office who could check your work and make sure you are heading in the right direction? If you have already formatted it in this way, as simple as a Dummies book, while following the company guidelines, I would say you have done your job. The only way to know for sure is to hand it over and get feedback. But it does sound to me like you may be overthinking and overanalysing it with tools like Hemingway. It's just a tool to help you, not to be followed blindly. Perhaps drop a comment on here and let us know if they were happy with it! Good luck. – GGx - Reinstate Monica Cellio Apr 5 at 12:51
  • I did a read-aloud edit, so I found some errors (some formatting, some were misphrasings), but later today I'll declare it "done." I've met with one co-writer a little, but she has her own projects. She told me that first draft wasn't what I'd call a first draft, but it should be "as complete/correct as possible." (Partially I asked this question due to the tag-of-the-week question drive, not pure anxiety) – April --Un-Slander Monica-- Apr 5 at 13:10

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.