Hero in you, or how to make your text easier to read

Most of us think that movies and comics are the only places where real heroes dwell. We believe that these mysterious guys just come from nowhere to save the day, and then disappear till the next time when everything goes completely wrong.

But that is not how it actually works. Real heroes surround us, and we meet them every day while commuting, working, or even drinking tea at the nearby restaurant.

For example, I know a guy whose name is Mike. He works as an Information Developer. Day by day, he creates help systems, reviews UI texts, prepares infographics. For sure, it does not sound that heroic or epic.

However, everything is not as simple as it may seem. Even though Mike looks like an ordinary person, actually he is a genuine superhero or even a true god among the mortal men. He cannot fly and he doesn’t have a super strength, yet you can be only astonished at how he can handle any task thrown on his way and complete with a lightning speed an astounding amount of work.

superhero

Mike always understands how things work from the inside and uses such superpowers as PRECISENESS,  CLEARNESS, and METICULOUSNESS to turn complicated technical stuff into a simple procedure.

As we all know, creating such documentation is a pretty tough challenge. It takes time and effort to explain all the nitty-gritty of some intricate process in an understandable way. But Mike knows his job well, and he works hard to help you along your way.

So, would you like to be like Mike? Would you like to save people from dark hands of AMBIGUITY, OBSCURITY, and DOUBT?

If yes, I have prepared some tips that will help you become someone’s superhero.

What to do, use, and ensure:

  • Write sentences as short and simple as possible. Try to keep sentences up to 25 words or less.
  • Ensure information is free of typographical errors.
  • Write in active voice whenever possible and use the present tense. For example, use “you have completed the signup procedure” instead of “the signup procedure has been completed by you.”
  • Use simple and clear coordination so the reader can tell what are the relationships between the elements of a sentence. For example, “the file or result field definition” could mean:
    • the result-field definition or the file
    • the file definition or the result-field definition
    • the file-field definition or the result-field definition
  • Use correct and consistent terminology. If you have used term “app” in the document at least once, do not use “application” in similar cases.
  • Selectively use terms that have different meanings in other environments. For example, use “conversion” for systems or programs, but use “translation” for national languages.
  • Allow space for text expansion, if your content will be localized or might be localized in the future. Some languages require more words to express an idea that may be expressed briefly in English.
  • Use 24-hour time format. Use international time formats. Do not use A.M. and P.M. notation unless you have no other choice. For example, use “at 14:00 o’clock” rather than “at 2 PM.”

What to avoid and not to use:

  • Avoid slang, jargon, humour, sarcasm, colloquialisms, and metaphors. For example, use “an estimate” instead of “ballpark figure.”
  • Do not use Latin abbreviations as they may be confusing for non-English speakers. Use “and so on” instead of “etc.”, “for example” instead of “e.g.”, “therefore” instead of “ergo.”
  • Avoid negative constructions. Use “it is like the previous request” rather than “it is not unlike the previous request” or “log on again to reconnect” instead of “you cannot reconnect without logging on again.”
  • Avoid the infinitive (to create), present participle (creating), and past participle (created) forms of verbs in the beginning of sentences. “completing steps” could mean “when you complete the steps” or “because you complete the steps.”
  • Avoid noun strings. For example, instead of “this app offers the delivery improvement assessment system” use “this app offers a system for assessment of the delivery improvement.”
  • Avoid using too many prepositions in a sentence, but do not omit prepositions or articles that are necessary. The sentence “this is a list of the current status of all event monitors for this process” could be rewritten to “this lists the current status of all event monitors for this process.”
  • Do not use slash to mean and/or. Rewrite the sentence to indicate the exact meaning. For example: “You can choose the green one, the blue one, or both.”

Hope these pieces of advice will come in handy for you. Of course, following them is only the first step on the way of becoming a real hero, but for sure, you will be heading in the right direction.

To sum up, I want to say that all of us can be heroes. Just figure out what are your powers and use them to the best of your ability. And remember, with great power comes great responsibility.


To join our order, visit our Hall of Justice where you can read about Information Developer superhero vacancies.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s