Whoa - I didn’t mean I hated them - I meant the OP should focus his hate on the right people. I have much respect for UA. Bear in mind also that they have to UI Freeze and go to press pretty early in the cycle - sometimes the product changes after that, and they always crunch it through. Props.
Full disclosure: I’ve been a Microsoft employee, specifically a PPT Dev since 1992, so I was speaking from the POV of a large company. More power to the smaller houses and the many hats they wear.
Ah, sorry, I see.
Wow. What an outstanding post.
I understand users’ frustration, but I work for a small software company as well, and I write some documentation for our software (our online knowledgebase, not in the actual software itself). It’s difficult because we have so much more oversight required for things that are actually in the software – old versions of the software with wrong documentation are still in the field and used by people – so the documentation is limited to things like basic how-tos and what various settings mean and isn’t comprehensive about frequently asked questions or troubleshooting information. While a very small number of people complain about this, in general nobody ever reads the software’s documentation. Most people will do a Google search before cracking open the manual, so it just makes more sense to keep things online on our website.
Even then, we regularly get support calls and emails about stuff that has nothing to do with our software – just as this fellow gets about Automator, which he doesn’t make. If we make software for X device, we get a billion questions about X other well-known software for that device, how to use the device, etc. and people complaining when we don’t (or can’t) answer their questions just because they happen to use our software too. Ultimately we have to put our foot down really hard because otherwise – being that we’re a small company that’s easy to reach, instead of a big company with a difficult-to-use call center with long hold times – we’ll be taken advantage of. It quickly becomes unprofitable when you’re selling software with a profit of $15 or $30 or whatever and people want hours of technical support help, or in-depth guides with pictures updated every time other company X puts out a new version and switches everything around again, to stuff that simply just doesn’t involve our software.
I understand that users get frustrated about who is responsible for what. It’s just that, from a software company’s perspective, many users want support to include anything that happens on or in a vague vicinity of their computer from whatever company whose software they used.
I have a great deal of respect for a developer who laid this on the line. Kudos to you, sir.
ETA: We don’t have a tech writer either. Documentation is either written by technical support staff or by upper management. Neither has any technical writing training, and I’m sure our work varies greatly in effectiveness.
As a former tech writer, I’ll vouch for the truth of this. “Sorry, we’re letting you go because we need to make some budget cuts and we’ve decided that the engineers and progrmmers can write the doc themselves.” It happened more than once.
I’ll add something else though, applicable to those shops that do have tech writers: don’t insist that everything I wrote be reviewed and approved by the engineers and programmers and marketers. I can write crystal-clear task-based instructions for the inexperienced end user, but the engineers and programmers often don’t understand that; and after they review such a user guide, they have been known to insist that changes be made. Such changes are those like the OP complains about: assumptions about the user’s level of competence, resulting in missing steps that puzzle the inexperienced user in some spots; and levels of detail that impart nothing but confusion and complication in others.
As for the marketers: their complaint always seemed to be that the doc didn’t sound important enough, and should be rewritten to use more complicated words and stuff, 'cause, y’know, it’s like, technical. :rolleyes:
bwaldie, I hope you stick around.
Also, I just bought a copy of your book. Automator is nifty.
ETA: Just in case it isn’t immediately obvious, Stoid is pretty much a raving narcissist. Don’t sweat her looniness.
–friedo, a fellow long-suffering software developer
This explains so much about that resume thread a few weeks ago.
bwaldie: With that post, you seriously made my (well the better part of) decade on the board. In fact, I am going to buy your book- and I don’t even use a Mac.
bwaldie, you are a credit to your profession.
Yes he is.
I wish to officially apologize to Ben Waldie, Owner and President of Automated Workflows, for making him the personal target of my frustration with many developers.
He and I have been communicating, and he is friendly, helpful, knowledgeable, patient and kind. He did not deserve to be called out like that and I think, I hope, he accepts my apology.
I’d also like to encourage all Mac dopers to explore the possibilities of Automator, and when you do, look into the incredible array of actions he has created.
Pretty much good advice for life in general.
May I suggest we get this out of Teh Pit and into someplace where it can be viewed by more of the Board? 
Let’s not spin cycles on that right now. We should be targeting on productizing synergy via componentizing end-to-end convergences in our Marketecture for aggregate strategic portals.
You left out “price point”. You must just be a marketing assistant.
You had me until you suggested software developers and their ilk were actually humans. =P
Select * from Users where clue > 0 and name = ‘ashman165’
0 rows found.
Done. Moved from The BBQ Pit to Mundane Pointless Stuff I Must Share.
Gfactor
Pit Moderator
Hrm, must be a coding error on your part. =P
I have a manual here for you to read over if it makes any sense to ya! =P
I am a writer who used to be a software developer. I wrote seven software users manuals (and one for a hardware product) before I got into writing more general rules. I have hired many a programmer and many a writer–and after I went freelance I contacted many software companies and offered to write manuals for them. I’d like to share a few things I’ve learned:
Perhaps 1% of the really good software engineers out there are capable of writing good user documentation.
Perhaps 0.1% are capable of writing really good user documentation.
Some days I think none of them are capable of writing excellent user documentation.
Very, very few companies are willing to pay what it costs to produce good documentation.
Most companies produce the manuals before the software is finished. Some have the manuals sent off to the printer while the specs are still changing.
Even companies that hire good writers to produce their documentation don’t understand that those writers should produce all of the help files and proofread every single screen, window, and dialog box in the program.
Since there are so few people capable of being a good software engineer and a good writer, the overwhelming majority of manuals end up either being written by mediocre writers or writers that don’t understand the product they’re documenting.
Tech writing is a discipline of its own. It isn’t the same as writing general nonfiction or novels.
You know what I find interesting?
How did bwaldie find this thread in under 3 hours of it being posted?
Did Stoid post it and then email bwaldie saying “HAHA I called you out on this messageboard! Pltttltltltlt”?
Has “marketecture” actually been spotted in the wild? Wow!