MANUAL STIMULATION: Whack me with some proper documentation Another day, another app, another incomprehensible user interface. If this was a proper piece of software running on a proper computer rather than a £500 phone, phablet or some similar pharcical phucking phanboi phondleslab, it might be possible to call up a Help menu or leaf through a manual. Instead, I’m left staring at a …
Good point, noting the illogic of my closing statement Ken!
What I really meant, before I just bashed away at the keyboard, was the high-level public documentation needed to make sense of many applications, which closed source products need (although many companies try and hide this information behind their "professional services" offer).
What is it with glyphs, icons, hieroglyphs etc? We've spent 3000 years developing a system for unambiguous written communication, and we're getting to the point where nearly everybody in the world can read it. But instruction leaflets and public signs increasingly consist of a set of glyphs and icons like some pre-school party game. I look forward to the law suit where the plaintiff says he couldn't understand the instructions for his chain saw because they were entirely in picture language, whereas grown-ups communicate in words.
Looks like a good thread to list my pet documentation peeves
1) Help/documentation that states the obvious but does not include any useful information.
e.g.
{insert name here} Button, press this button to do {whatever the name was} this will result in {whatever the name was happening}
with no clue as to the prerequisites are, why you would want to press the button anyway, any details to the consequences of pressing the button.
Automated documentation creation appears to be responsible for a significant volume of this stuff.
2) Video help, neither use nor ornament. by the time you have managed to get it paused on the single frame that contains the information you need to complete the task, you discover the resolution is too low to read it anyway. And how are you supposed to skim read a video for the one bit of information you actually need when it is in the audio after the point at which you gave up listening due to the umms, irrelevant information, annoying music and incomprehensible accent.
I could continue but it is bad for my blood pressure.
The following leads me to nominate the otherwise excellent Sublime Text editor.
I paid good bucks for it and this is what they have to say about their doc:
>The Sublime Text 2 Documentation is currently a work in progress. General. Sublime Text Unofficial Documentation is an excellent resource
Seriously, get a clue and write up something yourself. At $70 a pop, not asking too much, is it?
p.s. yes, yes, I still have ambitions to learn VIM. forgive me, I am a recovering KEdit junkie.
I worked on a three-year in-house training project for bespoke, undocumented software. We did a few tip-sheets for users but the system was so very complex that I wrote a mini manual in my own time to help the trainers. This was later made available to users, but by then it was out of date. I persuaded the project leader to let me write up proper documentation, and I began working on a proper hyperlinked manual in FrameMaker (so we could export to HTML and PDF from the same source files) but the project was wound up a few weeks later and I had to leave everything unfinished.
Another three years later, the software still hasn't been properly documented. If you choose Help or hit F1, nothing happens.
...let me just say that it's not just the engineers noted in the article; the simple fact is that EVERYONE hates manuals:
The engineers (as noted) hate documentation because they KNOW that their products are brilliantly intuitive and so NEED no documentation;
Marketing and sales hate documentation because, the more complete the documentation, the more complicated -- and, hence, harder to sell -- it makes the product look;
The bean-counters hate documentation because it's a cost and not a revenue-stream;
Management hates documentation because (being a non-revenue-enhancer) it negatively affects the bottom line and, despite that fact, you STILL have to dedicate facilities planning to its production, and;
As long as he can get the help-desk to read the manual to him over a toll-free number, the customer is never going to look at it anyway!
Once you realize all of this, it becomes very hard to maintain any enthusiasm for the job.
(* -- I got my start in tech pubs in the day of EMACS and NROFF, pulling pages off the spin writer, pasting up typeset chapter heads and graphics by hand, etc. Since the company was transitioning to WYSIWYG as I left, I ended up being the default "winner" of the prestigious "Worst Project To Ever Get Stuck On" award for spending a solid week doing manual assembly -- filling in lower-case "o"s by hand for bullet lists and hand-applying brackets and braces, among other atrocities -- for the company's 751 page PL/1 reference guide. I PAID my dues, guv!)
I used to write docs myself.
My niche was the game development tools industry: I wrote the user guide for Criterion's "Renderware 3" / "Renderware Graphics" (for which I can only apologise), and also the docs for the first few releases of Allegorithmic's "Substance" suite. I did some odds and ends for the Unity folks too some years ago. It's amazing how easy it is to find shockingly overpriced documentation tools that make even Emacs look like a simple, elegant editor by comparison.
"The engineers (as noted) hate documentation because they KNOW that their products are brilliantly intuitive and so NEED no documentation;"
This. Oh, so very this. (I lost count of the number of times I had to remind some of my colleagues what the "I" in "API" stood for. Developers can be end users too, so even an API should have basic UI design rules applied to it.)
Thing is, writing documentation really is a truly thankless task. Everybody hates what you do and considers your entire job pointless. End users have become so used to manuals being either missing, or abject shite, that they assume it's safe to expect this to be true of all applications. Not only do they never read your 500+ pages of bloody hard work, but they'll actually be surprised such a source of information even exists. And your own colleagues also see you as some kind of parasitic life form whose job appears to be ask them to explain what they consider blindingly obvious. There is nobody so blind as an expert.
Good technical authoring is bastard hard to do. Not only do you have to become an expert in the entire product you're documenting, you also need to be able to explain it to your readers without overwhelming them with information. Just enough background information – plus links to more in-depth info – and no more. And complex software can have features that rely heavily on other features too, so you need to organise the teaching to ensure you have full coverage.
Not everyone can do it effectively, despite many developers' belief in the contrary. Frankly, most developers I've met—include many with "Ph.D." after their names—seem to be either flat-out illiterate, or insist on making everything read like a particularly obtuse scientific paper. They sure as hell don't understand how to teach well.
Never mind that the greatest feature in the world is of no f*cking use to anybody if they can't work out how to use it. (Ironically, this is precisely how Apple have crawled out of near-bankruptcy to the top of the IT heap: they truly grok user education.)
I got the hell out when I realised that most of my potential clients had begun to see support as a chargeable feature, turning it into a revenue stream: a decent manual suddenly becomes a bad idea as it reduces support calls and, consequently, revenues from that particular stream. (Indeed, this appears to be how most GNU / FOSS applications are actually supported financially: write something that's genuinely useful, but give it a cryptic UI that effectively forces your customers to pay you for training and support and you can make a decent profit.)
I do translation now, which is a whole fresh hell of WTF in its own right, but at least people actually appreciate your work. They also don't tend to claim that "it's just writing! Anyone can write!"
A certain ERP vendor's documentation, just on the subject of SOA architecture, is about 1.5K pages long, in 5 manuals of 200-500 pages each.
Each chapter starts with the obligatory
"Understanding XXX.
The XXX delivered in your <vendor Name> system allows you to flexibly blah blah blah your business processes blah blah
"""
In the most common use case scenario, activating delivered SOA messages between 2 systems involves clicking on checkboxes in about 3 specific screens in each system to activate sub-components. And checking user security settings. Failures in establishing an initial connection with their SOA messages are usually directly caused by failing to do the above.
2000 pages to get there??? Without "how to get started with" doc?
This post has been deleted by its author
I used to write software manuals and help files for a living. Still do, but not often. The reason they have died out is not that they were too expensive to produce, but because of two related factors:
1. Users can't be bothered with learning how things work. As long as they can muddle through and get the job done, doing it elegantly and efficiently requires too much learning. If the function isn't obvious to a dozy user, it isn't important any more. Intuitiveness has trumped Efficiency in the marketing stakes.
2. Developers can't be bothered with designing things properly. Instead of starting with a functional design and usability analysis, then a technical design, then writing the code and documentation, then testing the results against the FS and UA, they make it up as they go along (it's called Agile, but it isn't).
Documenting this can only be done after it is finished because there are no proper specs to work from. And the code ships the day after it is finished (or the day before, all too often). So there is never time to do the documents!
Now, you say this, but there is a successful and lucrative industry in publishing 'missing manual' type books. They still sell quite well and software publishers are generally very happy for you to write them, even though they earn nothing from them.
I learned most of a computer language from the examples in a manual. This was possible because of the examples in the code.
I wonder how many people here have actually had to write a user manual for a substantial piece of software?
It comes down to 2 questions. 1)What do you want to say? 2)How do you want to say it?
Cookbook style? What we're going to do before doing it (so in future readers will know why they are doing it,and won't be completely lost when they deviate just a little from the script)?
Is it written for native languages speakers? People for whom this language is a 2nd language? Better be very careful with anything that might be ambiguous in comprehension. Better make sure those sentences only parse 1 way.
It's expensive, time consuming and difficult to get right and of course no one wants to do it and those who get roped in tend to think it's pretty easy, because its just words, right?
They are wrong.
All software can be classified into 2 types. Those that allow you to do a job and those that help you do a job.
The systems that help you do your job tend to understand something about your job and express that is some (usually arbitrary) set of commands. If you're lucky it's based on something the user is familiar with and it's commands do the same things in (more or less) the same way.
Of course to really f**k users up you need to make the UI work almost like a UI they are familiar with, but not quite. The "BOFH School" of UI design. :(
A case in point (between allowing and assisting) would be the use of Excel by Sales staff, when a CRM package could help them make much better use of their time, but means they have to learn how to use it.
"I wonder how many people here have actually had to write a user manual for a substantial piece of software?"
I once had to write a network troubleshooting manual for a distributed SCADA system for a major utility, for their operations staff to use. It was in the days when most IT staff might have known what a card reader was but didn't know what a modem was, and when the operations staff on the remote sites knew what to do with operational stuff but thought a computer was something they saw in War Games or the Italian Job.
Fortunately the whole setup had been so well designed and so well documented by the system architect (not me) that the troubleshooting manual simply had to reflect the faultfinding processes that had been envisaged at the time the setup was designed, just rewritten into terminology and procedures that would be appropriate for a skilled but not-very-technical audience.
That was mostly done in Runoff. It didn't really matter. The content mattered, not the presentation.
Now days the only thing English majors are doing is a little "You want fries with that?". Given that we have collectively dumbed down our understanding of language, we continually strive for the lowest common denominator and we get absolute junk. Sometimes it is a single piece of paper that is written in "Chinglish" that describes the older version of the software and us users need to extrapolate the next set of commands that will make it work. Other times it is "obvious" when the author of the software wrote it, and lucky you get to be Captain Obvious (which doesn't always work).
A well written manual is a joy to read, and you will find this out when you actually see one in the wild. Most are relegated to museums now days.
Then again, I'm reminded about my "Klopper" which although I don't have the item, I do have the Ikea-type instructions.
As for icons, pretty soon Unicode will have code points for all of them.
First of all, Alistair, just write down your passwords in a little notebook you can carry all the time. If anyone mugs you they'll grab your wallet, not some dull notebook they wouldn't know how to use.
As for manuals, that's a fascinating topic. Back when, software vendors did feel they had to write manuals and proper help. Then the light dawned: we don't have to be doing this.
1. If the software is at all popular, someone else will write a book about it and make a few bob for themselves.
2. Then, if anything in the book is wrong or incomplete, it's not your fault.
3. And you save all the time and effort that used to go into writing the manual and help. Which means you get to ship a year earlier.
Everyone's a winner! (Well, except the punters, but honestly if you start worrying about them...)
Oh God, this is *so* true.
Just a few days ago I got a collection of C++ source files, so downloaded MS Visual C++ Studio. Absolutely nowhere does it tell you how to just damn compile/build/make an existing project. Absolutely everything assumes that you are going to create something from scratch. Grrr. repeat(Gates' Head -> Wall).
Argh!! About a month ago I found a odd trojan on my system. Searching for removal information linked to video upon video upon video. What's wrong with (in this example) the single sentence: "Remove the HKLM/Software/blah/blah/blah/etc registry key." which is what all those videos boiled down to?
One of my least favorite stupidities are address forms that ask for one's complete address including postal (US - zip) codes. In the US each zip code is assigned to a specific post office that serves a specific area of a city/state. This data is readily available. But I can not ever remember seeing a webpage that automatically filled in the city and state when a zip code is entered. I assume postal codes are assigned much the same way in other countries.
For those complaining of having to listen to a US accent on a training video it is uncommon in the US to call the help line and get someone with an Indian or Pakistani accent. Often these agents are unintelligible to the average American. I would rather hear a Canadian (yes there is a distinct Canadian accent), British, Australian, Jamaican, or similar accents of native English speakers. Microsoft is very bad about this practice. Often when I do get an obvious native speaker of English, I am pleasantly surprised because it is so unusual.
I'm ashamed to admit that I have a big problem understanding thick accents at short notice.
Some time back, a software developer was so keen that I help with their alpha testing that they scheduled me in for weekly teleconferences with their developers in India. I did not understand a word during these phone calls. After saying "I'm sorry, could you repeat that?" and "Apologies, I didn't quite catch that" about 20 times, you come across as an idiot. I ended up feigning illness and suchlike simply to avoid that weekly teleconference, like a schoolboy trying to get out of Latin tests.
" The manual was 1 page long, and came in 50 languages. "
While in Germany a while back, I was expected to explain to a non-English-speaking friend of a friend how to set up their newly acquired satellite box to play MP3s and such like. I speak little German, and not that much geek, and had already failed to set up his new English-language printer on his German-language Windows box. Nevertheless....
The box was remarkably similar (in all but the badge) to one I knew from the UK, and hadn't had huge success with in terms of "advanced" stuff like timeshifting and other stuff. The supplied German/English/+2 manual wasn't similar. But my limited German was good enough to spot that the German pages actually were functionally different to the English pages. Unfortunately the box's behaviour didn't actually match either.
The joys of rebadging cheap generic Chinese stuff. The Korean stuff (Humax) is *so* much better (ffs if Humax is best in class, how bad can the rest be? Oh wait, I already know).
Yes I have had to write such a manual, for a mixed group of native and non native English speakers.
The company had fallen for Lie #1 of the software house's game. "This program is so intuitive it does not need staff training to use (or online help either IIRC)"
Not only are the help systems in Adobe products monumentally unhelpful, but they don't always work. We install all the Adobe products to hundreds of computers at work and one version of Photoshop (6 IIRC) would never allow access to the help system from within the program. I spend several hours testing and retesting the method I was using to deploy it and was able to reproduce the problem reliably. I was also able to reproduce the problem several times using a fresh install of Windows and a fresh install of photoshop (both done manually). I ended up having to get the automatic install to put a link to the help html files in the start menu.
Also, the error messages can be a little unhelpful. When exporting video, certain codecs impose certain restrictions (for instance Indeo required that the x and y resolutions be a multiple of 4 IIRC). Unfortunately, if the Codec refused to encode the video for whatever reason when you were exporting the video, Premiere just said there was a disk error..
…and was presently surprised that it came with an "operating instructions" booklet. A4-sized, and about 26 pages of actual content; with the remaining half dozen covering licensing agreements, specifications and warranty.
The instructions covered where all the ports were and some of the basics. So such manuals are still produced.
Automated spam blacklists! I tried to register for a forum the other day, only to have my registration denied because "your email and/or IP address have recently been used for spamming activity" or words to that effect. Now, I don't have access to a computer, I only have an iPod; nobody uses this iPod but me. It's unlikely anyone else would be using the address with which I attempted to register as it's an address I keep solely for the purpose of fora registrations and, being autistic, I don't tend to register for many fora.
So I emailed the forum owner and his response was basically "Tough shit - fuck off!" (Recently apparently means within the last 30 days).
Whilst I do, obviously, acknowledge that fora owners need a way of combatting spam, I DO think there MUST be a better way than assuming everyone's guilty and then forcing them to prove their innocence!
The forum in question was hosted by vBulletin, so I'm going to assume that all vBulletin fora are the same and avoid 'em all! I'm autistic (I got the "tough shit - fuck off!" response when I pointed this out to him and said that the instructions for jumping through the hoops I had to jump through to prove my 'worthiness' might as well have been written in some bizarre African tribal language for all the sense they made to me!)
I can't even leave the house at the moment - and haven't been able to do so for over 2 years - NOBODY is using this email/IP but me!
I DON'T much care for the insinuation, Mr. Up-Your-Own-Fucking-Arse-Admin!
The Register 
Biting the hand that feeds IT
Copyright. All rights reserved © 1998–2024
