Through the Looking Glass with User Guides!

Miscellaneous and Personal Stuff I Must Share
1

Holy mother of GOD how is it possible that you software engineers and programmers and generally all-around smarty-pants types are so extraordinarily incompetent, stupid and unbelievably infuriating when it comes to EXPLAINING your brilliant tool that would save my life and my sanity if I could penetrate the impenetrable, tail-chomping, “user guides” and “manuals” and “tutorials” that you provide.

I hate you.

There. I said it.

I HATE YOU!

Oh sure, I love you pieces for writing that software that does EXACTLY what I’m trying to accomplish…sez so right in the bright shiny promotional glurge all over your front page.

“Not only does SuperSoftwareBundle 7.9.3 read your mind and convey your thoughts directly to your computer’s memory chips, eliminating the need for you to do anything except ponder what you’d like to do next, it will find you a date! And that’s in addition to the backrubs and winning lotto numbers!”

I’m so excited! I want to get started right NOW!

Being a Mac weenie for 23 years, I never look at the instructions until I’ve poked around a bit. So I poke, I figure some things out, and these days, there’s tons of built-in information all over, just mouse over a button or whatever, and some little snippet will appear.

Great. Now I’m ready to look deeper, because your little snippets are not very clear. I’ve tried doing x and y, and reading carefully, but it’s not really coming through, it’s assuming I understand a lot of things going into this, and frankly, I’ve never worked with software that can read my mind and get me laid before, so you gotta lay some groundwork…

So I open the manualuserguidereadmetutorialhelpfile.

And in fact, they have considered that perhaps I’m not up to speed… so they spend 25 pages explaining how to install (click the button marked “continue” a bunch of times), how to check for the lastest update (which is going to include the only proven system for living forever, by the way!), and how to select menus. (Not to mention the five pages devoted to 4 different ways they have implemented for me to give them money for this magical tool that’s going to bring me orgasms, love, wealth and perfect happiness forever.)

And then leap from there to: “Once you’ve established the mindmeld, which is easy to determine because a flashing neon button starts blinking in the middle of the desktop, move to the bglurborooni and select the profile. Which will show the gleegendorf preferences you’ve set or that you’ve imported…”

WAIT! WAIT! STOP! WHERE ARE THE PAGES BETWEEN UPDATING AND THE MINDMELD??? HELP!!!

I have been known to spend HOURS trying to implement a single sentence of instruction, only to finally be told, when I track down some supergeek and hold him hostage til he explains it, that the writer of the sentence assumed I knew they meant that unlike three instructions immeidately preceding this particular instruction, this one is accomplished through a completely different interface by completely different means. Which is indicated absolutely nowhere.

Kinda like telling me (were I an alien) that I can acquire my dinner by killing critters with this here gun, shooting moose and squirrels and cows and rabbits.

And fish. I can also dine on fish. Which is actually ten times as delicious so I should probably make that my priority.

And completely failing to mention the whole water-pole-bait issue. Assuming that I’d somehow magically fill in those gaps, now that I know how to shoot a gun to kill a land mammal and all, fishing is nothing!

ARGH!

A more pedestrian real world example would be, for instance, automator scripts. Found one that seems like it might be very helpful:

WHat is available to read within Automator itself:

Umm. Well. This is just a tad vague for me. Seeing as how I’m not an Automator weenie. I’ve dabbled, but I’m just a user trying to use this tool that Apple provided for me to automate a few things without Applescript. And you guys wrote this cool action that seems helpful…Oh, you have DOCUMENTATION? Neat! And it’s over THREE HUNDRED PAGES? Wow! I’ll bet that’s incredibly comprehensive and helpful! Let me at it!

And this is the explanation of CHOOSE LIST ITEMS Provided in the 300-plus page manual:

Oh.

Really? That’s all you’ve got? Could you have at least faked it by providing all that information in complete sentences using subjects and verbs, nouns and adverbs and adjectives? Maybe a diagram? Just to humor me?

Wait…there’s SIX pages with multiple full-color images explaining exactly how to install the actions (psst: tell user double-click. End tell. Fuckoffihateyoudie.)?

And…it appears there’s SEVEN pages devoted to checking for updates and finding out what version you’re running?

Really??

And now that I look closer, I see you haven’t updated your website in the last 13 months?

(Stoid goes to weep in the corner…)
I really do hate you.
So much.

2

Sorry, dude. We went into comp. sci. because writing and communication skills were not our forte :wink:

3

I get that.

Hire people who could never do comp.sci. but can effectively explain rocket science to the lost tribes of the amazon. Then let that person loose on your software and make yourself available for questions. Then pay them to write it down in a way that’s readily accessible to the average person.

And then I’ll pay you.

I cannot tell you the number of programs I have passed on that I was ready to write a check for if I could just get some decent documentation and support. My favorite thing in life is a big fat PDF just brimming with the tiniest details. Because your software is useless to me if I can’t figure out how to run it.

4

Software engineers and programmers have nothing whatsoever to do with writing Help Files and User Guides. Hate the UA / Tech Writers.

Software engineers and programmers have nothing whatsoever to do with bright shiny promotional glurge. Hate the Marketers.

5

tldr

:smiley:

6

This.

Also user guides and help files are for sissies, Real Men just poke around until they get it to work.

7

Stoid,

While I am always open to feedback and criticism, it’s things like this that sometimes just make me want to give up being a software developer.

I can’t sufficiently describe the amount of harsh, rude, and sometimes incoherent feedback that I receive from users regarding a wide variety of issues, on a wide variety of topics. Typically, I assume its because email (or, this this case, a forum posting) is a poor medium for communication (no way to express actual emotion, other than underlines, italics, or all caps), something has been misinterpreted, or the user simply doesn’t realize that their feedback will be read by a live, honest to goodness human being. Despite this, I always respond personally to every request I receive. Why do I do this? Because (a) it’s in my nature to help people, and (b) I know what it’s like to be on the other end.

Throughout my years as a software developer, I have never hesitated to share my expertise and help others whenever it’s possible to do so. This goes for users of my products, as well as people just looking for assistance. I have written countless articles, spoken at conferences, helped people write code, walked people through issues by phone and email, I could go on forever. When someone emails me with a question or problem (no matter how harsh they may come across), I always try to respond, get to the root of the problem, and help them to the best of my ability, usually without cost.

For those with common questions, I have created a repository of answers, and provided a forum for them to communicate. Since the creation of my online support forum, I have personally responded to every question ever posted.

For those who seek knowledge, I have created an extensive free “Tips” section on my website, with links to my many tutorials, tips, articles, podcasts, and more, despite the fact that sharing this knowledge may encourage competition and may in fact hurt business down the road.

For those who seek additional education and learning at a cost, I have written books and authored video training courses.

Again, I could go on. The bottom line is, I am always happy to help, and whenever possible, to do so for free. In your case, had you emailed me with questions about how my product works, or requested sample workflows for performing specific tasks, I would have been happy to help you to accomplish your goal. Instead, you have posted a steaming, scathing rant about my lack of documentation. So, let me address this specific concern.

The fact of the matter is that most people’s difficulty using my actions comes from their inability to understand how Automator itself works. As you know, I didn’t write Automator. Apple did. And, as you might expect, Apple doesn’t provide significant documentation on how to use it. In fact, Apple doesn’t even have a web page on Automator anymore. For these reasons, I literally wrote the book on Automator, in which I cover all the ins and outs of virtually every aspect of Automator. The documentation for my product assumes that the user has a knowledge of Automator. For those who don’t want to invest in my book, as mentioned above, the “Tips” section of my website includes numerous articles, blog posts, and podcasts (all of which are available for free), which cover the basics.

I also provide a few free sample workflows to help get people started. However, everyone’s workflows are different. And, I’ve written (now) 170 actions for performing various tasks. So, for me to provide useful sample workflows for each and every action is simply not practical or feasible for me at this time.

Back to the documentation. You’re right, it could certainly be expanded to be more comprehensive. That said, an Automator action doesn’t require an insignificant amount of time to create. At minimum, every action requires several hours of planning, development, and testing. My point is that, it took considerable time to create 170 actions. Since I barely make enough money from these actions to justify the time it takes me to create them (not to mention nights and weekends taken away from my wife and kids), at the time of their release, it became a matter of (a) should I release the actions so people can start using them and I can begin recouping some of my investment, or (b) should I spent the next three months of nights and weekends extending the documentation. As you might have determined, I chose the former. I also fear that you are in the minority, and that most users don’t actually open the documentation. I know this because the topics, such as installation, which is covered in extreme detail in my documentation, continue to be some of the primary topics for which I receive support inquiries.

The bottom line is that my company is small. I handle all development, promotion, documentation, etc. myself. Furthermore, I don’t make a living from my Automator actions or other shareware products. The cost I charge for the actions does not nearly cover the investment. I make my living from custom development, which consumes the majority of my time. I provide Automator actions as best I can, with my limited spare time, to help people become more efficient with some basic tasks at a reasonable cost and to help Automator itself gain marketshare.

That all said, as with all feedback I receive, I’ve added your suggestion to extend the documentation to my list, and will consider doing it in a future release of the actions. However, this will be dependent on (a) whether I decide to continue releasing actions that aren’t financially viable, (b) I’m able to do so in a reasonable amount of time, and © expanding the documentation doesn’t take precedence over other, more highly requested enhancements.

Now, I’d love to continue my rant about your rant, but I’ve got a family to care for and a small business to run.

Sincerely,

-Ben Waldie
President, Automated Workflows, LLC

P.S. If you really do need some help with one of my actions, send me an email to ben at automatedworkflows dot com, and I’ll be happy to try to help you.

8

The other day my wife couldn’t get her Gmail password to work. I gently offered my help/gruffly shoved her aside (depends on who you ask, though I’ll admit that the words, “If you weren’t such an incompetent with computers…” might’ve crossed my lips), tried variations on her password, got a screen that asked her Secret Question (What was your first telephone number?), got THREE variations out of her (“It kept changing. At first all I had to do was ask Sarah to connect me to my aunt.”), keyed in every variation on them I could imagine (Google is proud to say they don’t limit the number of tries you get, which makes wardialing Gmail passwords an option), then gave up and logged into their message board for help (Google is also proud to say that they don’t have phone help for their free services, which isn’t surprising because I tried to find the MAIN Google phone number for business reasons and couldn’t find it).

The first response pointed me to the screen with the Secret Question. I did NOT say, “Asshole, I’m a guy and would not be asking this if I hadn’t poked around everywhere first.” I suggested it might have something to do with that day’s IE8 patch, and other people posted that they had the same problem. I figured the boffins at Google would fix it now that there were multiple bug reports and went to bed.

The next morning she was up and running. “What did you do,” I asked.

“They write this software so that people as incompetent as me can use it. I just changed my password.”

Which I would’ve done the night before IF IT HAD LET ME. But no, I was just too smart and educated. :rolleyes:

9

applauds

10

I’ll third this.

I can’t tell you how many times I’ve tried to make something easier to use, or presented better, or whatever, only to be shot down by the Marketers. Or the Product Managers, who want it out NOW and to hell with it being usable or good.

Tech writers are usually pretty good, but they’re brought in at the last moment and given 2 weeks to write documentation on a product that takes 2 months to learn how to use well.

And, of course, some of it is the consumer themselves - the demand that software be FREE and available NOW has not helped the software industry much. Every time I read a post on this or other forums where someone is trying to find a piece of software that creates flowcharts, is voice-activated, mows the lawn, gives you a massage, and makes a mean martini but oh-by-the-way it has to be free, I sit on my hands in order to not write back a not-so-cordial response.

11

This is a bit of a cop-out.

Sure, some consumers have unreasonable expectations, but the fact is that most people recognize the difference between free software and software they pay for. If i’ve downloaded something for free off the internet, i’m not surprised if the documentation isn’t as comprehensive as i might like. But if i’ve forked over $100 or $200 (or whatever) for a program, then i should be able to learn to use the program by reading the documentation.

Also, while there are some smart and generous souls out there providing free software just because it makes them feel good, plenty of free programs are produced by for-profit companies as advertising or as loss leaders for their business. There’s nothing wrong with that, of course, but it’s not just greedy consumers who drive the free software business.

12

And sometimes people who rant about documentation are thick as a brick.

As part of my job I write tutorials for my department for specific functions of Major Market Software, the brand name of which rhymes with Bicrosoft. I write these tutorials because (a) we’ve customized parts of the software for our use, so the tutorials cover those customized parts but mostly (b) because they can’t be bothered to use the built-in help, the online help our organization provides,the Bicrosoft web site, the reference library I maintain, nor the 10,000,000 blogs/tutorials/whatever that are out there on the Internets. Noooooooo, it has to be something super-baby simple with lots of pictures that addresses their exact particular need at that particular second, in which I’ve intuitively anticipated the weird vocabulary they use to describe things rather than what things are actually called. And THEN I still get the panicked/angry phone call or email when something didn’t go right. My response? I walk through the steps in the tutorial with them, which if they’d actually read would have avoided the problem in the first place.

I’ll tell ya another thing – a lot of people who complain about software documentation are trying to use what I call “professional grade” software, which is not something you can just jump into and play around with for 15 minutes and figure out. This is not a Mac/PC issue, BTW. Photoshop is an excellent example. Some people – professional graphics folks – make a lifetime study of Photoshop. If you already know photography/color space/darkroom techniques, or even just have a good artist’s eye, you have a leg up. If you want to hop into Photoshop to get the red-eye out of the pictures of your dog, and you don’t know where to even begin to accomplish that, it’s not the software’s fault nor the documentation’s fault.

13

I understand the latter sentiment entirely, but why do you hate the tech writers? You’re running down your own products by making them inaccessible.

14

Been using personal computers since there were personal computers. It has been my experience with software manuals, that they will tell you what each function does. They do NOT tell you how each function can be used.

That’s the way it is. Ranting & pitting will not change that.

For that kind of information, you must visit your local book store and shell out the scratch for a How-To book on your software of choice.

15

Often not true. In fact, Ben Waldie who came in to respond to Stoid’s post stated that his “company is small. I handle all development, promotion, documentation, etc. myself.”

IME the engineers and programmers are often asked to provide the documentation because either the company is very small (and there is no budget for a tech writer) or the management are very stupid (and there is no budget for a tech writer). :slight_smile:

Pretty much true. :slight_smile:

And a note for all you managers out there who think that integrating that 3rd party product will be much easier than getting the development department to write something for you: their glossy brochure is lying.

I mean, you know that our “bright shiny promotional glurge” is lying; what on earth makes you think theirs is accurate?!

16

FTR, I LIKE to write step-by-step, “click this and then click that,” instructions. I can often do it while on the phone and not actually looking at the screen. But in this business climate I might as well be illiterate for all the good it does me in finding a job without a Masters in User Interfaces.

17

If only. Some manuals may tell you this. I have found numerous instances of software with functions that is not even referenced in the manual. And yes, I am talking about software I paid for.

18

You just haven’t run into the right programmers. Personally, I’ve been complimented more than once on the clarity and usefulness of my written instructions.

When I write instructions, I just assume I’m writing for total idiots who can barely work a mouse. I don’t assume anything. I go into every stinkin’ tiny little detail and I use lots of screen shots. You have to aim for the lowest common denominator.

19

Sir, you are trying to reason with an unreasonable person. I wish you luck.

20

Actually, hate the managers who don’t allocate enough resources for UA/tech writing. You’ll also often find that not enough time is allocated up-front to developing good use cases either, which has a cascading effect on the rest of the project.

Feel free to continue hating the marketers, though :slight_smile:

And on a related note: Developing software to be used by one person is easy. Developing software to be used by a hundred million people is a bit more challenging. The more user profiles (or personas, if you prefer that term) you need to support, the more complex your software and design processes need to be. Since every project is resource-limited, this means that not all users are going to be able to do what they want as easily as they want.