How Not to Write Technical Documentation: 10 Tips to Render User Helpless

0. Ghost-Tip. Never waste your time for introduction.

1. Be general. Don’t go into details, you don’t need to provide actual information. Write “The software is useful.” Enlisting the spheres of application is for dummies. Your readers are the best. They are working as prophets and reading your mind in their free time. Why spell it out for them?
Other questions you definitely don’t need answering:

  • Where is the command located?
  • Why is that command used?
  • What is the name of the command?
  • What is the sequence of the steps?
  • What effect will the procedure produce?

2. Don’t think about target audience. You are ace at what you do. Why limit yourself? Write whatever you like. Explain whatever you fancy. You do remember that you are dealing with prophets whose expertize should not be doubted. Oh, we are thinking about users. Shoot, drop it!

3. Go for the easiest. Your program is feature-rich and can provide complex solutions. Who cares? Give users a simple workflow and trust me, if they needed something more complex, they would come up with something. Buy software of the rivals, for example… Anyway. You are not here to help and serve their majesties.

4. In maximalism we trust. Have not heard of it? Let me guess, you believe that being concise and succinct, providing minimum sufficient information will lead you somewhere? Save readers’ time and efforts? Don’t be ridiculous! Light your inner star and let it shine through luxurious texts. The more startdust-peppered text—the better.

5. Keep repeating. Repetition is the mother of wisdom. So why put repetitive steps in a separate procedure? Users won’t forgive you unless you exhaust their attention with all possible information.

6. Complete your work with long inappropriate tips. Not sure where to place vital information? Put it into the tip and make it long, so that a user will never ever bother to read it. I would put a three-paragraph tip here to support my point, but you would skip it anyway. Oh, that already proves it, right?

7. Bless users with your opinion and assumptions. Help users become your fans in no time. To be a user’s idol, try “Almost certainly, you are reading this chapter because your manager asked you” or “You might want to do that if, for example, it would be best that your boss or your spouse didn’t know what you’ve been up to.”

8. Add terms diversity. If you can, why miss a show-off opportunity? Coherence is overrated. A user would definitely enjoy: “Point to submenu, also known as cascading menu, hierarchical menu, or secondary menu.”

9. Forget conventions of grammar and spelling. Holy spell check should not be holy anyway. Unchain yourself from all the limitations. Explore ABC boundaries and text users patients test users’ patience. It’s not even your competence at stake 🙂

10. Language. Emotional flowery language. Let’s face it—technical documentation can be boring. You are better than that. New Windows? It must be “a brand-spankin’-fresh Windows.” Got the vibe?

11. This article should be called 11 tips. Irritated that the title does not reflect the content? Pff…

Author’s Note

╰(*´︶`*)╯♡

Hi there! With this post, I didn’t mean to be judgy or ridicule someone or something. The list is not exhaustive, and the statements are not absolute truth. Just it may be a good checklist and a proper laugh for you.

Advertisements

11 thoughts on “How Not to Write Technical Documentation: 10 Tips to Render User Helpless

  1. Lesia Zasadna says:

    LOL!
    There are so many posts on how to write – but really, why not play the Devil’s advocate?

    I say:
    Liberate your irregular artistic self and apply local formatting back and forth! 😉

    Passing on the #renderuserhelpless challenge to @araguena ))

    Liked by 7 people

  2. Iryna Sushko says:

    Challenge accepted!
    I say break the rules, create your own – who’d want to have cautions & tips right where they need them? Meh, too boring. 3 steps before or after is a pretty good place to start off 🙂

    Passing on the #renderuserhelpless challenge to @nataliiabortkevych

    Liked by 7 people

  3. To make users even more helpless, never provide screenshots!
    You are a philologist, writing is your profession and a calling. You know that your text is brilliant and totally self-sufficient. Why be so primitive and rely on images? Let them cry at a mere glance at your lengthy procedures and descriptions that span on and on without any graphics to make the learning process easier.
    Having said that, I pass the #renderuserhelpless challenge to @ireneboliubakh !

    Liked by 7 people

    • Irene Boliubakh says:

      If lengthy procedures and absent screenshots isn’t enough punishment and your cruel soul still isn’t satiated, discard the formatting at all! Why bother with highlighting the name of controls, with applying different style for code samples, with accentuating headings? Plain text – and no distracting bold and italic whatsoever. We all know that the beauty is simplicity, right?

      I pass ##renderuserhelpless challenge to @marianakuchynska!

      Liked by 9 people

  4. Mariana Kuchynska says:

    Oh, this is fun! I’d say lose links as such. Let user show their brilliance saying “it was already mentioned” somewhere in the document. User can definitely find it if they read your masterpiece from cover to cover.
    And this even adds a gamification element, so you’ll be in trend.
    Good luck guys! I mean “dear users” 🙂

    I pass ##renderuserhelpless challenge to @halynaiakymchuk

    Liked by 8 people

  5. Halyna Iakymchuk says:

    Wow! Girls, you are so creative, that I truly sympathize our users.
    Well, my suggestion would be the extravagant color scheme (for example, yellow text on green background, red text on black background, or worse). Let’s enrich user experience 🙂
    And, by the way, why bother creating documentation originally in English? Let’s check whether they still remember how to use dictionaries.
    With this said, I pass the #renderuserhelpless challenge to @nataliasavchyn

    Liked by 7 people

  6. Natalia Savchyn says:

    Ladies, why would you be so mean with your readers? 😦

    No links, no graphics, local formatting, are you serious?

    C’mon! Be transparent with your end users! In Release Notes, let that sweet 50-year-old housewife know that the new version of her favorite grocery shopping app has been improved with a substantial reduction of Get () methods to the production database in the process of basket calls refactoring.

    Because.. this is exactly what will convince her to upgrade, right?

    @katerynasasnyk, what do you say?

    Liked by 5 people

    • Kate Sasnyk says:

      Love your ideas! They are soo… handy 🙂
      I’d also recommend using notes in your writing, and the more – the better. Place 3 or more notes in a row one after another so that the user spends more time in your precious document finding the needed information – that’s how we make the users read the documentation!
      Aa-a-and, the challenge goes to @oksanasukh – share your tips!

      Liked by 4 people

  7. oksanasukh says:

    Why not boast of your brilliant knowledge of English grammar!

    Remember to use inversion, ellipsis, and cleft sentences. Do not take a blind bit of notice of localization. Who cares that the grammar and syntax of different languages can make it difficult to match the structures in English?

    Be yourself! Create an uproar!

    Passing on the #renderuserhelpless challenge to @antontwriter.

    Liked by 4 people

  8. Anton says:

    Old school is always better!
    The relevance of primordial volumes of knowledge should never be underestimated! Use Pre-IMB standards and regulations where the wisdom and wit of the Ancients are thriving in abundance.
    Follow the mighty soviet GOST and let docs from the 90s lead your way through the bewildering array of contemporary technics.

    @larry_kunz,do you have something to add?

    Liked by 6 people

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