16 votes

I can't make it any clearer. Any advice?

Last Thursday, at my workplace, we rolled out a software upgrade across the company. The server side was upgraded overnight to ensure there was minimal downtime, and we had instructions for users posted on our Intranet (pinned to the top for the next 4 days), on exactly what they needed to do to run the upgrade on their PCs and ensure everything was working correctly.

The instructions were written with the help of my 4-year-old to ensure it was clear enough for anyone to read and follow along.

I still received at least 40 messages and emails from people complaining the upgrade didn't work or that certain Outlook plugins are now missing (which was covered in the instructions).

My question is, has anyone found a good way to ensure people follow instructions, or the best way to ensure that your instructions are easy to understand and follow along with?

It is very frustrating to take the time to ensure things go smoothly and write what even my 4-year-old thought was clear instruction, and still have a third of the company not be able to figure it out?

This is not meant to be mean hearted in any way, I genuinely would like some advice or tips on how I can improve on this the next time around.

Thanks.

34 comments

  1. [4]
    helloworld
    Link
    Do you know how many times I read our intranet? Zero. If its not in an email sent multiple times over multiple weeks, I don't know about it. It is not about being a dick, which I can be sometimes,...

    Do you know how many times I read our intranet? Zero. If its not in an email sent multiple times over multiple weeks, I don't know about it. It is not about being a dick, which I can be sometimes, but it is about being so overwhelmed with a million other things, that this stuff that usually just works, slips mind.

    Email and multiple reminders. As the other commented said, this will cut down your requests by 75% or more. It also makes more likely that a confused user gets instructions from someone else within the team who might have noticed the mails.

    26 votes
    1. [3]
      mmarco2121
      Link Parent
      Unfortunately, our management has mandated use of the Intranet as the main means of communication and the place to get updates from across the office. We have not had a single all-staff email in...

      Unfortunately, our management has mandated use of the Intranet as the main means of communication and the place to get updates from across the office. We have not had a single all-staff email in almost a year and a half.

      2 votes
      1. [2]
        helloworld
        Link Parent
        Your management is a smart one then. I have half a dozen folders and double that rules in outlook to filter out the crap every unique snowflake of a department sends company wide, and some still...

        Your management is a smart one then. I have half a dozen folders and double that rules in outlook to filter out the crap every unique snowflake of a department sends company wide, and some still slip through to inbox.

        Staff-wide mails can turn into slippery slope, so in this case, I'm not sure what else can be done. Maybe try those pesky Windows Notifications MS uses to nag about various pre-loaded bs. You can have them just like mails and include link to intranet post. Put them to actual good use for once. Not sure how that can be done technically though, just a suggestion.

        2 votes
        1. mmarco2121
          Link Parent
          That’s actually a great idea. I will look into if this is possible. Thanks.

          That’s actually a great idea. I will look into if this is possible. Thanks.

          1 vote
  2. [6]
    AugustusFerdinand
    Link
    The only way to do this that I've found is to completely take it out of their control via management software.

    The only way to do this that I've found is to completely take it out of their control via management software.

    14 votes
    1. Amarok
      Link Parent
      Bingo. Hell, I worked at a company that was 98% developers and they were no better than secretaries or management in this regard - just far more entitled and entertaining. :) We have powershell...

      Bingo. Hell, I worked at a company that was 98% developers and they were no better than secretaries or management in this regard - just far more entitled and entertaining. :) We have powershell now. That's a long, long way from old school windows where automation was difficult. If you can do it in the GUI, you can do it better with a powershell script. I'd have attached a script for this to an update push and rolled it in with the usual patches and updates, whenever the reboots come around - likely over a weekend.

      There are always edge cases - the one guy using some whacked outlook plugin that no sane person should be using for example. That's just Monday morning's support queue.

      5 votes
    2. [3]
      mmarco2121
      Link Parent
      I really wish with this particular install I could have done it. Unfortunately, we could not get it to work. But the majority of the issue came from the steps after the upgrade. The PC needed to...

      I really wish with this particular install I could have done it. Unfortunately, we could not get it to work.

      But the majority of the issue came from the steps after the upgrade.

      The PC needed to be restarted and then the program needed to be launched before launching Outlook so that the plug-in would load correctly.

      This step was bolded.

      2 votes
      1. [2]
        Akir
        Link Parent
        Of course, it's a problem with Outlook. The world would be a better place without it.

        Outlook

        Of course, it's a problem with Outlook. The world would be a better place without it.

        2 votes
    3. joplin
      Link Parent
      Yeah, actions speak louder than words. Show - don't tell. I work on a desktop app with an API that allows 3rd parties to write plug-ins for our software. We also have a system that allows 3rd...

      Yeah, actions speak louder than words. Show - don't tell.

      I work on a desktop app with an API that allows 3rd parties to write plug-ins for our software. We also have a system that allows 3rd parties to create templates for end users. The developers that have the most success selling to our customers have a system where, every time the app starts up and loads plug-ins, their plug-in checks to see if all of its pieces are installed and if not, downloads them from the internet and re-installs them. It also checks all the templates it supplies and if any are missing or have been modified, it downloads them from the vendor and reinstalls them. It makes launching our app slower, but it keeps their customers happy and avoids problems like, "That last OS upgrade nuked my templates folder and I lost all the templates I paid for!" All the alternatives like putting up a dialog to say pieces are missing or modified, or just throwing errors end up with worse outcomes for both users and the developer.

      So is there a way you could write some sort of installer or configurator in the future? IT's probably a big ask, but if you can, it might mitigate this problem or at least make it easier for users to fix the problem. When you get an email saying "it's broke!" send the updater/configurator tool and say, "Just double click this and let it run, then try again."

      1 vote
  3. [2]
    spit-evil-olive-tips
    Link
    How often is this "pinned" feature used, and for what sort of other notifications? If it's used for both "urgent: read these upgrade instructions or your computer will stop working" and "hey, sign...

    we had instructions for users posted on our Intranet (pinned to the top for the next 4 days)

    How often is this "pinned" feature used, and for what sort of other notifications?

    If it's used for both "urgent: read these upgrade instructions or your computer will stop working" and "hey, sign up for the company softball league" then I think it's entirely possible many users gloss right over it.

    I also like Bottom Line Up Front style communication for this. If it's something you want everyone to see, send an email (realistically, multiple emails) with a BLUF of something like:

    We're upgrading some IT stuff. Everything on your computer will still work, but your action will be required as part of the upgrade

    At most companies, there's all sorts of "oh fyi, some things are happening" emails, Slack messages, etc. Unless you make it very clear, people will default to the assumption you're sending them an FYI message and not a you need to do something as a result of reading this message.

    8 votes
    1. mmarco2121
      Link Parent
      Messages are pinned when important information is needed to be read. Usually by management or IT. I had a please read in bold in the title.

      Messages are pinned when important information is needed to be read. Usually by management or IT.

      I had a please read in bold in the title.

  4. [4]
    viridian
    Link
    You may have to tailor different messages for different audiences. Where I work, we can with broad strokes separate folks we support via software into technical professionals, non technical...

    You may have to tailor different messages for different audiences. Where I work, we can with broad strokes separate folks we support via software into technical professionals, non technical professionals, and medical professionals. We typically provide very different messaging for each group based on our past experiences.

    The big thing is that without big bold, explicit instructions, repeated over and over, in different ways, we will be overwhelmed with complaints and tickets filed from the medical professionals.

    That said, even if we are so clear as to allow for no possible way to mis-understand what has changed and how it affects usage, we'll still get some volume of complaints about the update invalidated the user's password, or caused an unrelated browser issue, but it cuts our support volume by 75% or so.

    6 votes
    1. [3]
      mmarco2121
      Link Parent
      Thanks. I know there will always be some people that just cannot figure it out. But it almost felt like no one bothered to read the instructions. I got to the point where I literally just pasted...

      Thanks. I know there will always be some people that just cannot figure it out. But it almost felt like no one bothered to read the instructions. I got to the point where I literally just pasted the instructions in the email or chat message, forcing them to read it and follow along. They were simple steps:

      Click icon and allow update to run.

      Restart computer.

      Launch updated app.

      Then launch Outlook.

      That's it. Nothing special or difficult to do.

      1 vote
      1. [2]
        iiv
        Link Parent
        Click which icon? How do I allow update to run? How do I restart the computer? How do I launch Outlook?

        Click which icon? How do I allow update to run?

        How do I restart the computer?

        How do I launch Outlook?

        5 votes
        1. mmarco2121
          Link Parent
          This is a fair comment, but our workplace is technology forward, with the majority age of staff between 25-35. They should know how to restart a computer and launch an application. The program is...

          This is a fair comment, but our workplace is technology forward, with the majority age of staff between 25-35. They should know how to restart a computer and launch an application.

          The program is used heavily in daily workflow.

          There’s only so much hand holding I can do without coming across as condescending.

          Or am I wrong to assume that?

          1 vote
  5. [6]
    ohyran
    (edited )
    Link
    The absolutely best way to make someone follow instructions is to be there with them, let them see what you do, copy what you do, then listen to your explanation of what you did and what they...

    The absolutely best way to make someone follow instructions is to be there with them, let them see what you do, copy what you do, then listen to your explanation of what you did and what they should do. Which isn't possible for 180 people obviously.

    So for text...
    You need to make the information shocking enough to notice, enticing enough to keep reading, tailored to the reader enough that the information is quickly grasped, and rewarding when understood.
    It can't be boring, it can't be overly complex or too long, and it can't feel meaningless when completed.

    We're humans, we live in a society with information overload. So we sort out almost everything as fluff unless it relevant enough to be focused on. Our interests have made us able to sort things in to "things I care about" and "things I don't care about" fairly quickly and we can look like we're taking in information even when our brains are set to "autodelete" behind our eyes.

    We are also quickly bored. A book called "The Super Secret Life of Mmarco2121" might be interesting for you to open obviously, but if it started with 200 pages of things you already knew that isn't very revealing or relevant ("Mmarco eats snacks, here are common snacks that most people enjoy") you get bored and ignore it. Or skip ahead carelessly (missing the third paragraph on page 138: "Mmarco also killed a man in 1982, left him for dead in a ditch. This man survived and is now hunting Mmarco").

    It has to feel rewarding in the end. See you want to make it easier NEXT time. If people feel rewarded for reading it, they remember it or remember this and will be better at attaining information next time. That said - this is tricky. People remember failures and bad things better than good things and successes. A normal success is forgotten, but a normal failure sticks in there.
    It doesn't have to be relevant for the action the text is ment to achieve, just relevant for the text. But "ending on a positive" is always good.

    Recap:

    1. Shocking enough to notice
    2. Enticing enough to keep focus
    3. Quickly grasped if focus is lacking
    4. Rewarding when completed

    One way is to abuse human interaction...
    Use a human medium. Basically delegate the information to people who you can explain the process to in person (say 18 people), that each work in one area (with 10 others) that they can go from desk to desk and be part of that information chain in a trusted manner. People who can show, be copied, and listened to - and who in turn can report back issues to you.

    But perhaps that is a big thing for a company - you are after all stealing 18 people from their daily routine.

    So you may need to use marketing tactics...
    Looking at the "text" methods we can crank it up to 11 and look at humans and how to best hack their ability to take in information.

    So lets say you can print out pamphlets. Often in modern offices a pamphlet on your keyboard is shocking and different compared to an email on the intranet. So if you can get the right to print something - print it in colour and on glossy paper.
    People like the feel of glossy paper and it looks different from how normal stuff in an office is with the copy machine spitting out A4's folded by you.
    The reason people keep magazines with glossy or thicker paper more than matte or thinner cover paper is that we put value in touch and tactile experiences. Something different, or heavy, or slick feels more relevant to us as a species. This is why IKEA (and similar) catalogues are still printed, on glossy paper, and heavier, with more void-pages than is truly necessary to crank up weight.

    Put a face on top of it looking at the camera. Preferably attractive. Everyone likes attractive people. We as humans ace the ability of recognizing faces so a face looking "at us" always grabs our attention more than something without a face looking at us.
    Check out the glossy magazine rack at your local supermarket, notice how its one of three things usually on the cover: A photo of food, a photo of a recognizable celebrity, or a face looking "at you".
    Don't be too specific with the title. Keep it short, vague, but focus on the relevance for the reader. An example of this is B2B phone salesmen back in the day that would use a method where they stood up, introduced themselves by name only with a serious voice asking for that person by name in turn. This because that makes it suddenly scary to the person without attaching the fear to the speaker. Has something happened at your kids school? Is this the tax office? Why do they know my name? When you got the persons full attention the salesman would sit down again, smile while talking on the phone and be more cordial.

    Each page of this pamphlet has a photo on top, preferably with a strong but mellow main colour (so say "Powder Blue") and if possible a human and a screen grab of the thing they need to do. Underneath is a list of actions in a numbered fashion to show how its done, put a header with the specific subject named above. Avoid adding text. Finish with a link to a webpage with more information on this specific action. [Photo] -> [Header with clear subject] -> [Concrete List] -> [A way to find more information on that subject alone].

    If you can afford it: space it out! Make each open page pair have one subject each. So instead of a book, see each open face of two pages as one singular thing. That means that its easier to find. Each flipped page changes subject so going back means finding the subject you need quicker as you don't have to read past the page break (where you flip a page). Try to use different mellow colours for each subjects photo.
    Try to use a language as if the reader is actually doing the steps along with you. Start the pamphlet by saying "Lets upgrade this now!" and then have the text go "Now, click this icon [screen grab of icon in its setting, so people find it easier]. Now that you've clicked it, let it run while you do something else on the computer" (to keep it from going asleep if thats an issue, no need to tell them that though)

    The linked page at the bottom should lead to a page with the same base colour as the colour of the photo used, a link to a contact email (you) if there are problems, and a link to a list of the other subject pages. You don't have to make it fancy here. Add indepth information of each step and issues that may arise and how to solve them. Just clear and boring.

    At the end include either a joke pertaining to the subject of the pamphlet. So say like XKCD comics. Or memeish funsies. They are funnier because the reader feels "in the know" and included on the joke. Since they understand and few others do.
    Another, perhaps more easily attained is a photo of a group of ok looking people smiling at the camera doing like a thumbs up or something and the text "Awesome work" or a positive hope "Together we are making this happen" or something.
    We are as a species more dog like than we pretend. We all want to be a part of a group, if the group taking us in is good looking or have qualities we value highly we feel even better about it, and being praised - even by a photo - feels great.

    End with your email again to make sure questions are directed at you.

    Recap:

    1. Paper not email
    2. Consider touch - glossy+heavy > thin+matte
    3. People looking at the camera
    4. Vague but relevant on the front.
    5. Simple interior. Large photo, short list. One per open page-set
    6. Further information available but elsewhere
    7. Use colours, don't make it drab
    8. Make it easy to contact you
    9. End on the positive.

    resources
    A collection of free to use photographs https://unsplash.com/

    EDIT: Just wanted this said - people aren't dumb for being human. We are shit at certain things, and fail certain things because as a species its not in our most common tool box.
    A cat isn't dumb for being scared by the vacuum cleaner. It does it because its species is a midlevel predator with other predators above it in the food chain. So loud noises are problematic.
    So this is not a text with the underlying hint of "humans are morons" - rather one saying "We're humans. We have a thousand and one things in our heads at all time, and we can only do so much. But this is a way to ensure that the information is made as accessible as possible for one of that species"

    4 votes
    1. [5]
      mmarco2121
      Link Parent
      Thank you for such a lengthy response! I know humans will be humans. We’re busy, and thinking of a million different things at once. I know this all too well in my current role. But at the same...

      Thank you for such a lengthy response!

      I know humans will be humans. We’re busy, and thinking of a million different things at once. I know this all too well in my current role.

      But at the same time, it is a workplace and there is a certain level of expectation to be able to follow instructions.

      2 votes
      1. [4]
        ohyran
        Link Parent
        True but also things like company loyalty or engagement in the work etc, but we don't have that either. Because we are just not able to. If you write out the post as "Critical information, read...

        But at the same time, it is a workplace and there is a certain level of expectation to be able to follow instructions.

        True but also things like company loyalty or engagement in the work etc, but we don't have that either. Because we are just not able to. If you write out the post as "Critical information, read and follow exactly as part of your work duties" - that would cover the shock and enticing bit though? Because then people will think they might lose their jobs or something if not.
        That said it will probably make them dislike you personally.

        The issue is whether you want to talk in a way that makes them hear, or be disappointed that they don't?

        2 votes
        1. [3]
          mmarco2121
          Link Parent
          Fair points. I will try some new things next time around. See if things get any better. Thanks.

          Fair points. I will try some new things next time around. See if things get any better.

          Thanks.

          1 vote
          1. [2]
            ohyran
            Link Parent
            Ok and now I realize my last post sounded kinda dickish. It IS annoying that you have to do more work for something thats, lets face it, not your part of the work... and I am rooting for you here.

            Ok and now I realize my last post sounded kinda dickish. It IS annoying that you have to do more work for something thats, lets face it, not your part of the work... and I am rooting for you here.

            1 vote
            1. mmarco2121
              Link Parent
              Haha no worries. My post was part venting and part seeking actual things I could try next time. So thank you for taking the time to help out. It is appreciated.

              Haha no worries.

              My post was part venting and part seeking actual things I could try next time. So thank you for taking the time to help out. It is appreciated.

              2 votes
  6. nothis
    (edited )
    Link
    Read this book and slap your fingers whenever you notice yourself blaming people for being stupid. It's not their job to be experts at this. You did something wrong. Or the software did something...

    Read this book and slap your fingers whenever you notice yourself blaming people for being stupid. It's not their job to be experts at this. You did something wrong. Or the software did something wrong. Anyways, apologize and try to look at what exactly confuses people, it's probably a simple, stupid thing, and try to fix it. Maybe it's literally the order of two words in a sentence. Maybe your very important instructions land in some random folder constantly spammed with useless stuff and not real notification?

    I just noticed my bank sent me a really important message over the bank's online messaging tool, 2 months ago. I didn't see it, not because I "can't read" but because the notification drowned in a pool of attention-grabbing popups.

    Also: Your 4 year old didn't understand shit, I mean, I get the frustration but come on!

    4 votes
  7. [4]
    CrazyOtter
    Link
    Can you post the instructions? It sounds like you did a good job if 140/180 people had no problems upgrading. Maybe it's a problem with visibility like others have said.

    Can you post the instructions?

    It sounds like you did a good job if 140/180 people had no problems upgrading. Maybe it's a problem with visibility like others have said.

    3 votes
    1. [3]
      mmarco2121
      Link Parent
      It might be a problem with visibility. However, our intranet is the mandated way to get info on across company happenings. We are not allowed to use all-staff emails. Haven’t for at least a year...

      It might be a problem with visibility. However, our intranet is the mandated way to get info on across company happenings. We are not allowed to use all-staff emails. Haven’t for at least a year now.

      Management made it clear that all communications happen via our intranet and managers are supposed to discuss any important news in their department meetings.

      So theoretically everyone should have seen/read/heard about the upgrade and the instructions were posted at the top of the home page feed, bold and easy to follow.

      2 votes
      1. [2]
        cfabbro
        (edited )
        Link Parent
        But in practice? My experience with most "management mandated" things is that most employees still largely ignore them and/or find ways around them. And when it comes to stickied elements in...

        So theoretically everyone should have seen/read/heard about the upgrade

        But in practice? My experience with most "management mandated" things is that most employees still largely ignore them and/or find ways around them.

        And when it comes to stickied elements in particular, at least on websites, IMO element blindness quite often comes into play there. E.g. On reddit, users quite regularly will make brand new posts asking for information that is already very clearly included in the sticky at the top of the subreddit, or in the sidebar... and the reason for that is their eyes automatically skip over and brain automatically filters out those element for them, since they are used to the stuff contained there generally being pretty useless to them the majority of the time.

        5 votes
        1. mmarco2121
          Link Parent
          Interesting take. Makes sense. I’ll keep this in mind. Thanks.

          Interesting take. Makes sense. I’ll keep this in mind. Thanks.

          1 vote
  8. [2]
    skybrian
    Link
    I don’t think there is any way to keep people from asking, but maybe reply with a link or a canned response? Maybe beta-test with some actual users? Once someone has helped out a bit, you might...

    I don’t think there is any way to keep people from asking, but maybe reply with a link or a canned response?

    Maybe beta-test with some actual users? Once someone has helped out a bit, you might need to retest with someone else to get fresh eyes.

    Just curious, 40 out of how many?

    2 votes
    1. mmarco2121
      Link Parent
      Thanks. 180 total. We had tested with a small group of about 10 and the instructions worked for them. They ranged from technical people to non-technical.

      Thanks. 180 total.

      We had tested with a small group of about 10 and the instructions worked for them. They ranged from technical people to non-technical.

      3 votes
  9. PendingKetchup
    Link
    There might be a limit to how widely known you can make an announcement just by posting it on a web page. I myself spend a lot of mental effort ignoring announcements, banners, advertisements, and...

    There might be a limit to how widely known you can make an announcement just by posting it on a web page.

    I myself spend a lot of mental effort ignoring announcements, banners, advertisements, and other attention grabbers. I am actively using my whole brain for my current task, and if I drop something from my working memory to comprehend an announcement, which has a low probability of being important to me and my task anyway, I will fail at the thing I opened my email or the intranet to accomplish.

    If I do need to act, "Action Required" or something similar needs to hit my brain before I can determine that I am looking at an announcement. And action has to be 100% actually required by me every time, or the signal will lose effectiveness. And when I act I need to be able to dismiss the message rather than ignore it.

    You might have better luck with a sign in the bathroom (if you had a physical bathroom), or somewhere else people are bored, rather than a notice on an intranet page nobody goes to without a task in mind.

    Maybe rather than focusing on pre-education, you need to intercept people between when they discover something is wrong and when you have to manually deal with them. If you make a big breaking change, don't let people open a ticket until they type "Running the fix application does not solve my problem" on a page about the current upheaval.

    1 vote
  10. [3]
    Staross
    Link
    Just a wild idea but why not go in person in the office and ask orally to everybody if they have heard about and understood the instruction. Personally I often rely on my colleagues explaining me...

    Just a wild idea but why not go in person in the office and ask orally to everybody if they have heard about and understood the instruction. Personally I often rely on my colleagues explaining me what to do rather than reading instructions (it's just much easier).

    1. mmarco2121
      Link Parent
      We are all remote working...

      We are all remote working...

    2. [2]
      Comment deleted by author
      Link Parent
      1. Staross
        Link Parent
        Never saw anybody do that.

        Never saw anybody do that.

  11. wcerfgba
    Link
    Is there a way to get feedback on the pinned post? Like an emoji reaction to a Slack message? If you put an instruction "Please +1 this post after you have read it" then you could gauge how many...

    Is there a way to get feedback on the pinned post? Like an emoji reaction to a Slack message? If you put an instruction "Please +1 this post after you have read it" then you could gauge how many people saw and read the post.