Cameron was a support rep for a Unix-based software package that had also been ported to Windows and Mac OS X. He supported every version, and quickly learned that not all ports were created equal.

Click Here. No, Here

The Windows port was the angel of the pair. The developers had written an installer with NSIS that created an icon on the Desktop for users to double-click. It worked well enough that Cameron almost never fielded Windows install support tickets.

The Mac port was the devil from a support standpoint, and there was really no good reason for it. As long as Xcode and X11 were installed on the user's machine, everything worked perfectly. However, few Mac users had these libraries out of the box.

No problem. On their product download webpage, they supplied links not just to their own installer, but also for the Xcode and X11 installers. And yet, the number of users calling in to flail helplessly were numerous.

"What link? I don't see it anywhere!"

"The installer's on another site?"

"What do I do now?"

When Cameron walked users through the process verbally, it always went fine. He got so much practice at it that the instructions were practically encoded into his neurons.

One day, Cameron had a sanity-preserving idea. He ran it past his boss, who then set up a meeting with the product website masters.

"We field a ton of calls for this Xcode and X11 install stuff," Cameron explained. "No one can figure it out without some help. I'd like to set up a webpage describing the whole install process step-by-step. I think it'll really cut down on the confusion. I know HTML, I can put the page together myself with screenshots and everything."

Everyone agreed it was a good idea. After some minor negotiating, the web team agreed to give Cameron access to the product website's test domain. "Write up the page you want. Once you get it how you want it, we'll QA it, then promote it," they told him.

The opportunity to do something outside the same old support work was exciting to Cameron. His HTML experience came from all the personal websites he'd thrown together since the days of Geocities, and wasn't too shabby. He put together a nice step-by-step breakdown, describing every detail of going to the appropriate external website and running the installers, with screenshots and links to everything the users would need. In the screenshots, he painstakingly indicated each button and link to click with little circles and arrows.

His boss liked the page, praising his "moron-proof," thorough instructions. The page went live soon after. Cameron looked forward to spending more time on more challenging support tasks.

A few months later, he resigned himself to the bitter reality that nothing had changed. It seemed no one on the planet could perform the Mac install unassisted. He fielded calls from end users all the way up to "network administrators" and "tech professionals."

"It doesn't work for me! Nothing happens when I click the links!"

"I followed your instructions to the letter, but the icons didn't work."

"Nothing happened."

Strangely, each time Cameron walked someone through the process, everything went fine. He couldn't understand it.

Neither could his boss, who wanted to reduce this pain point for his support staff. He approached Cameron one day with a suggestion. "Hey, we're doing a trial of this new remote viewing tool. It'll let us see exactly what users are doing, and dig into their systems directly if we have to. Would you like to try using it to see what the deal is with these Mac installs?"

"Sure!" Cameron was willing to try anything.

It didn't take long for another call to test on. "When I click the icon, nothing happens," the user explained to Cameron.

"All right." Annoying, but old hat by that point. "I'm gonna email you a link to a remote viewing session. This'll let me watch your install process. Can you click that link when you get it?"

"Sure."

They were connected a few moments later. The man's kitten-festooned desktop filled Cameron's view.

"OK, can you go to your browser and walk me through what you're trying to do?" Cameron asked.

"OK." The user opened up a new browser window and clicked a bookmark in the toolbar. "First, I go to your product page."

It loaded obediently a few moments later.

"I go to the instruction page …" He clicked the link to Cameron's how-to page. "Scroll down here a bit … then I click this icon, and nothing happens."

Cameron looked on in mute horror as the user furiously clicked a screenshot displaying the X11 icon with a circle around it. The 3x3-inch screenshot that he'd been careful to label "Screen Shot" in big letters.

"Oh. Uh …" Are you kidding me? This is what everyone's doing?! Cameron took a deep, calming breath before continuing. "That's not where you want to be clicking. Just a little higher than that is a link that says ‘Click here to open the Xcode install page in a new window.' Can you try that one?"

"OK." The user complied, and the Xcode site loaded obediently.

"There we go!"

Cameron had no trouble walking the user through the rest of the process. Afterward, he sat back with a frown, thinking. Should he remove the screenshots? No, they were important for illustrating what to do on the Xcode and X11 websites. There was a better way to handle this, he was certain.

He took to Google. After a little research on Javascript onclick events, he contacted the web maintenance team, describing the change he wanted to make.

Sure! they emailed back. Do it in test and tell us when you're done.

From there, Cameron added a script to his webpage so that whenever someone clicked on any screenshot, a window popped up that read, "You are clicking on a screenshot within our instructions. In the Xcode/X11 website, find the window that resembles the screenshot and click on the icon there."

[Advertisement] BuildMaster allows you to create a self-service release management platform that allows different teams to manage their applications. Explore how!