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 …
I have the all the same issues. However my present hell is interpreting why a web site will not let me register.
A certain mobile phone company complained I had not filled in all my details despite the fact i clearly had. Eventually I worked out I was registering a username that was already assigned.
Fortunately I know enough about websites and those who design them to work my way through the issue(First rule. If it doesn't work, try another browser. Usually IE). But many, including my wife is often driven to hysteria by such problems.
But many, including my wife is often driven to hysteria by such problems.
In the case of my wife it's hysteria that starts with the sound of an Intellimouse being slammed down on to her desk so hard that you have to admire how indestructible they are. This will be closely followed by a scream for help, which I now answer with a reminder of how she doesn't want me near her computer ever since I accidentally changed the wallpaper.
I seem to be married to your stateside doppelganger. May I make a few suggestions that may prevent said intellimouse being imbedded in your skull?
1. Don't preface your remarks with a lugubrious sigh that implies the asker is a dunce.
2. When told that she has already performed some actions to attempt to remedy the problem on her own, DO NOT walk in and immediately PERFORM THE SAME ACTIONS, as though your God-like touch will somehow cause the machine to behave.
3. Do not seize the mouse or keyboard, do something that causes the desired result and then WALK AWAY WITHOUT EXPLAINING what you did and why you did it.
You will live long and prosper more if the above suggestions are kept in mind.
Re: blanking out all the fields.
The website creators are obviously total plonkers when it comes to usability. Nil Points.
I'm also passworded out especially, the extra security password that some banks are tacking on to Debit and Credit card transactions. I change it an immediately (not even a few seconds) after doing so it has gone from my memory.
As regards documentation. I can remember the work that went into getting the DEC VMS V5.0 Doc set printed. It seemed at one time almost every printer in Eire was doing something for the release.
Online documentation leaves a lot to be desired. Be it 'man' pages that have no examples at all to the maze of circular references that are many IBM Infocentres they are IMHO CRAP.
The best example of in your face docs I have ever come upon was the DEC 'DCL' command language. Totally structured with examples.
now what was the password to my 'router' again?
(answer, it is on a bit of paper under my UPS)
Do you remember the container loads of manuals that, for instance, VMS came with? But at least they were there and worked even when the computer did not.
I detest these badly filmed videos in which a monotone, American voice speaks in some obscure dialect, using American "cool" references and words, probably about baseball or whatever they play and completely fails to hold your attention long enough to find out what he is trying to say or show. All I want is to find out how to move a page from a to z (that's Zed, not some confusing Zee or was it See? Can't tell with that drawl).
Then the same person seems to write the manuals, on line or paper and litters them with super-friendly quips and jokes, illustrated with some quaint Americanisms from his local school or some such and still manages to obscure or hide the information you seek. All I wanted was an instruction, up to date, to the point and with no unnecessary cruft.
Do you remember the container loads of manuals that, for instance, VMS came with?
I certainly do. Six feet of shelf space. Even more remarkably, I think I read about 60% of them.
super-friendly quips and jokes
No jokes in the VMS manuals, admittedly. But I recall one of the RSTS manuals that described the excruciating process of linking executables in such a way that the system could swap overlay segments in and out of memory. The linker in question was called the task builder, and the manual contained a full-page cartoon of a workman, with the caption "Tommy the Taskbuilder".
I never read the DEC manuals (that wasn't my machine,) but I did read all of the Honeywell manuals for CP-6. Less than a month later I was promoted from lab assistant to system administrator.
I will admit to being waaaay over my head while reading the PL/6 manual.
<rant>
All of the manuals, that I need to read today, have been written as lists of commands and options...and that's mostly it. No well reasoned examples that tell you how to do ______. Just "Here's what the command looks like with all of its mutually exclusive options" crap.
</rant>
Cookbooks (recipes of common tasks) are sometimes more useful than a full manual.
My favourite was the AIPS cookbook (for the Astronomical Image Processing System) which also added banana recipes to the software ones.
Icon: apparently she has a 'banana' body type. I am sure readers can also imagine other connotations.
"I'm also passworded out especially, the extra security password that some banks are tacking on to Debit and Credit card transactions...."
Verified by Visa, and whatever the Mastercard one is called - I hate those!
They crop up sometimes, but not frequently enough that the password has really registered in my brain through repetition, so by the next time I use it I can't remember what it was last time, and then have to choose a new one. Of course all the new ones I try it rejects because I've used them some time in the past, so I have to choose a new-new one that's not nearly as memorable as any of the ones I wanted to use... so of course, the next time, some months later, Verified by Visa pops up... and I have to go through the whole rigmarole again!
"I'm also passworded out especially, the extra security password that some banks are tacking on to Debit and Credit card transactions...."
Then there's the dreaded Dual Authentication
Look it's simple.
The mobile phone signal near my computer can be a bit hit and miss so sometimes I have to go outside to get the SMS containing this vital piece of login information.
Please don't throw a "session expired" message at me when I've had to do that.
... and try doing it for a card that's registered outside the country of issue. Every time failing memory requires me to set a new password on my UK-issued HSBC Visa card my Polish postcode - which is shown on my account statements - is rejected and I have to endure all the pleasures of the voicemail system and ask some callcentre slave for help.
The other extreme annoyance I have with many websites... entering credit card details.
My card number is presented on my card with a space between every group of four digits. A computer is very capable of stripping out such card numbers when processing the number. So why the **** do so many websites insist that the number is put in without any spaces? Or, as is often the case, just error when you do and don't indicate why.
The other occasions when I'm wound up by entering card details, is when the website numpty insists on putting names instead of numbers for the start and end months. I've never come across a card with names instead of numbers so why was this website doing this? When challenged, they claim to have done this idiocy on purpose to stop bots.
"It isn't difficult to strip out spaces!!"
It certainly isn't.
And it's really not at all difficult to insert spaces so that a phone number looks like it does in the phone book or printed on letterheads. Ditto for credit card numbers.
My latest online form filling adventure rejected my phone number because i simply copied and pasted it from elsewhere.
Duh!
And it's really not at all difficult to insert spaces so that a phone number looks like it does in the phone book or printed on letterheads.
You think so? What's the correct spacing for a French phone number? A UK one? Swiss?
Website forms should obey Postel's instructions from the very early RFCs. Be liberal in what you accept, and conservative in what you send.
Some UK phone numbers only have 5 digits in them - my wife's shop in Somerset on the 01460 code for instance. Imagine my surprise, when checking estimated broadband speed from a communications company beginning with B, (and ending in T) the website rejected the number as invalid.
BT go one better with their ADSL checker:
<https://www.btwholesale.com/pages/static/Community/Broadband_Community/Coverage/ADSL_Availibility_Checker.html>
If you do key in a number with a space, it will truncate the number string to 11 digits and then remove the space before attempting a number lookup which naturally will fail. Obviously only the observant will notice the missing end digit(s) from the returned number.
I hate forms that insist on a postcode. And insist on a city. I end up with:
City: Hong Kong
Postcode: HK
Country: Hong Kong [You put it in the select list!]
And is it too much trouble to actually say what phone number format you expect? Country code or no country code? Is "+" accepted?
It is even easier to write "do not leave spaces" onto the form, to give the user a bit of a clue.....
Best trick was an email provider which kept refusing your proposed password, with no explanation, unless you figured out all by yourself that they expect lower and upper case and a number and a symbol. (After a few months of this they finally woke up to themselves and are now telling people this secret).
"My card number is presented on my card with a space between every group of four digits. A computer is very capable of stripping out such card numbers when processing the number. So why the **** do so many websites insist that the number is put in without any spaces? Or, as is often the case, just error when you do and don't indicate why."
True.
Imagine this.
Four 4 digit long (with only digits allowed) with automatic moving between the boxes.
You can't believe there isn't some bit of pre fab'd code to do this, and that it wasn't written a decade ago.
"Four 4 digit long (with only digits allowed) with automatic moving between the boxes."
Actually used to hate forms with automatic moving between boxes as I'm so used to tabbing to get to the next entry I was always ending up in the wrong box, and if you make a mistake on the last digit in a box, it's already moved onto the next box so you can't just press delete to correct it.
@JimmyPage, as somebody with an apostrophe in their surname and a reasonable knowledge of the website innards (having supported a few), it never ceases to amaze how many fall at such a seemingly simple hurdle.
I remember looking at some ASP code years ago and thinking "why the hell are they building the SQL on the fly, why don't they just use parameters instead?"
The other benefit is that it makes you less vulnerable to wonderful things like SQL injection, pause for obligatory xkcd reference:
http://xkcd.com/327/
Oh and when it comes to validating input items on a webpage, please either stop the user from entering the verboten characters in the first place, or even better, make the validation interactive so it checks the field as you're populating it and either shows a cheery green tick or a red frowny face along with a suitably annoying message.
I don't want to get to the bottom of something that resembles a morttgage application only to find out then that my chosen username is taken or that you can't find my fscking address!
Any website that has hacked me off to that extent is simply left behind whilst I Google an alternative that does give a stuff about the UI and HCI side of things.
Many years ago I saw a post on an educational IT forum from someone at Crapita (who write the SIMS school MIS database package)
They explained how they had to be quite insistent with the developers that names like O'Connell and O'Dwyer existed and would need to be dealt with...
I remember in a previous life as a software tester, I was testing form validation.
I got to the email field, tried the usual - null, incorrect variants, correct variants, all was fine until I got to this test:
a.b.c@d-e-f.com
The email address validator spew out a validation message.
I drew the developer's attention to this (was trying to be nice, rather than contribute to a growing defect report list...) and he said that that was because the domain was invalid.
I showed him d-n-a.net (which now redirects to UTVInternet), he said 'oh' and quietly edited the regex.
So are uppercase letters. :(
The reported error was simply "invalid email address" and I had to view the HTML source and find the offending script to figure out WTF it was complaining about. I think it was for some school-related website so I imagine that folks without a working knowledge of Javascript just aren't allowed to have kids these days.
With them, the older the software, the better the manuals.
The early language ones were superb, and could have been sold separately as language tutorials. The later ones were printed on soft toilet paper and, if you were lucky, covered what was new in the libraries.
Thinking about this, it does feel true. The older the software/manuals, the better the manuals were.
These days you often can't even find a manual when there should be one, even online.
... grumbles and glares at HP for providing a paper version of a disclaimer in 50 languages, and included a CD with the same but failed to provide even a basic "this is the product and what to expect from it" one page manual sheet. It may have been just a docking station, but knowing that it was expected to have lights on the network connector and the specification of the network connector would have been nice when troubleshooting it :)
The mention of HP brings to mind one of my first student jobs in which the task was to wade through a cabinet of HP1000 documentation binders and chuck out the duplicates. I became quite the HP1000 anorak from reading the unwanted manuals that I hauled back home...
Did you know that the largest core module was 4KB but the high speed memory controller only supports semiconductor memory modules?
"Did you want to know" is another question entirely...!
Borland TASM (x86 assembler) circa the late 90s came with a printed instruction set reference (every x86 instruction, what they did, their binary encodings, what flags were effected and how) and an extensive user manual (I only remember chapters on "object oriented programming in assembler", "calling conventions", and enough BNF to re-implement TASM if the mood took me).
Visual Studio Express 2013 for desktop's idea of "help" was allowing me to select from a list which help packages I'd like to download for offline before telling me, "You don't have the required permissions to perform this action", with no indication of which "permissions" or, for that matter, which "action". (This sort of stuff is why non-tech people only use the admin account! )
Ain't progress grand?
Given that your example is Visual Studio Express 2013, I think that should read "This sort of stuff is why tech people use free software -- it's just less depressing when it doesn't work if you didn't actually pay for it.".
Why? they never did before!
Microsoft manuals were always cheery descriptions of everything going right, with the word Microsoft repeated on every line. Mention of problems? Probably banned. Mention of Microsoft product without using (yet again AAaaarrrgh!) the word "Microsoft," banned.
My first ever computer came with a manual. A slim volume described the hardware and the rest of the shelf was devoted to Unix. Good grief, there was even a fat volume on writing device drivers, though I never graduated to an understanding of it. That shelf of manuals was, for me, the foundation of a new career
A few years into that career, I started getting marketing material from IBM. It was curious stuff, which told me how the product would revolutionise my business --- but left me wondering what the hell the product actually was! Informix literature was much the same. Of course, that might have been after IBM bought them.
As to the nnnn nnnn nnnn nnnn of credit/debit cards, maybe the question we should ask is what idiots put the spaces in them in the first place?
Humans can't really read numbers without separators.
It's much easier to check for typos if you can check "block #2" instead of "digits 5-8".
nnnnnnnnnmnnnnnn
You should never ask the user to type blocks of 'random' alphanumerics longer than ~5 characters, assuming you want them to be typed accurately.
"I think Microsoft could afford a proper manual."
Back in the day, they did. I still have a copy of the Microsoft Windows NT System Guide vintage 1993; a task-oriented guide to how to do things in Windows NT (3.1? It's not obvious). An actual user manual. I also had a complete set of manuals for Office Pro (?) from a similar era - proper printed manuals for Access, Excel, Powerpoint, and Word. Junked them recently, kept the System Guide as a reminder that the business end of MS used to understand what was needed.
VMS manuals have deservedly been mentioned, but actually the DEC hardware and software manuals in general were in a class rarely seen in recent years. The focus was on content and not presentation, though once they moved from Runoff to VAX Document (via some others) even the presentation was good. Authoring a quality document was apparently easy enough too, unlike with (say) Word.
Manuals written by people who knew their product and knew their audiences (end users, system managers, programmers, field service engineers, even potential purchasers - different audiences with different needs) and knew how to write comprehensible english. Even the presales literature was worth a look. What a concept.
Is proper vendor-produced documentation inconceivable today? I've been impressed with what I've seen from Xilinx when I briefly played with FPGAs - are they really OK, are there other examples of how software/system documentation should be done, is it just MS that see it as yet another revenue opportunity for themselves or a partner?
The MicroVMS documentation set deserves particular mention. MicroVMS was just a repackaging of VMS targetted for MicroVAXes, around the VMS V4 era, and it came with a little known and short lived custom docset which disappeared once VMS on CD arrived and DECwindows and CD documentation came with it. It was a very small number (basically 2 manuals plus administrivia such as release notes) of compact manuals focused on the things that were most likely to be useful to most people (so not a complete reference, but a very usefuly desktop library, for small desktops).
[1] MicroVMS User's Primer AA-Z210C-TE 1985 partly available at
books.google.co.uk/books?id=nnK4AAAAIAAJ
MicroVMS Users Manual Parts 1 and 2 (not online? boo hiss?)
ps
El Reg: This eight day old article is still open for comments. Earlier today I wanted to comment on a two day old article [2] and comments are already closed. What gives?
Fwiw, what I wanted to say there was that USB->serial adapters are only OK if your requirements are simple. If your requirements are more complex, e.g. require low latency/rapid turnround, generic USB-serial may bring challenges, e.g. simple ping-pong protocols suddenly take N (e.g. ~5) times as long to compete a given task, because the latency between port and app goes from zero to multiple milliseconds, and if your protocol is immutably set in stone by (e.g.) a machine vendor and there are literally millions of pings and pongs because what you're doing is downloading a multimegabyte program byte by byte before you can process the next item on the production line... well USB to serial isn't helpful.
Relevant here too, because you will largely find this out by bitter experience rather than by reading the manuals. FTDIchip's USB->232 docs may mention this, but how many folks are aware of FTDIchip let alone the USB latency/turnround issue?
[2] http://forums.theregister.co.uk/forum/1/2013/11/21/migrating_from_windows_xp_time_to_move_on/
We're seeing the results of thorough computerisation of all sorts of ancillary tasks surrounding software development (and not only that.) A good technical manual is a feat of organisation, and lots of people suck at organisation. In times past, there were trained professionals who could take care of such things -- technical writers, secretaries, archivists. No more: everyone's expected to do everything themselves, with the excuse that there are those excellent software tools to make it possible, but tools are useless -- or worse, seemingly useful -- in untrained hands. Cost-cutting all the way; the mask of knowledge and efficiency is wearing thin, and the truth of an average bloke's (and blokette's) muddle-headedness shows through.
These deserve a much fuller treatment than given here.
I tried to learn Blender a year or so ago - a product with a notoriously inscrutable user interface. All the tutorials are in video form and EVERY SINGLE ONE includes at least five minutes of some microcephalic idiot saying "um" a lot, explaining what product the tutorial is about (thanks, I know, that's why I'm watching the tutorial), saying "um" some more, explaining what he's going to explain in the tutorial (thanks, I know, that's why I'm watching the tutorial), saying "ah" quite a bit, presumably to alleviate the boredom (his, not mine) and explaining why you'd want to do what he's going to explain in the tutorial (thanks, I know, that WHY i'M WATCHING THE FS!CKING TUTORIAL). It's as though they expect people to just sit there watching a random stream of tutorial videos and so need to say up front what the tutorial's about.
Another pet peeve is websites that do have a 'Documentation' tab but, when you get there, have an explanation of how great the product is but no actual instructions on how to use it (yes, www.beremiz.org, I'm looking at you). Or even worse, a documentation link that leads to an empty wiki - See? It's YOUR fault there's no documentation, you haven't created it yet!
This post has been deleted by its author
"My other pet hate is the shit-munching video tutorial. I fail to see how spending a quarter of an hour watching a blurry rectangle of illegibility while an American spits and wheezes into a microphone that’s so muffled it might as well have been be shoved up his arse is superior to reading a step-by-step workthrough that I could complete myself in less than five minutes."
This sums up my entire attitude to modern help files. Yes, in a minority of cases, seeing what is supposed to happen is useful, but in general that can be done with words and stills - video not required!
I can quite happily have netbeans or some other user friendly behemoth on one half (2/3) of my laptop screen and some free flowing html that tells me how do what I need to learn on the other half(1/3) .
But paper shaped documents need to be on a separate workspace to be legible are just a sodding pain as are website designed by designers and not users.
And video can fuck right off.
I hate video tutorials because you have to watch the whole thing, can't skip to "the bit that I got stuck on" etc.
Plus they are really hard to make and usually get outdated in the very next release.
Yet I regularly get requests from users for "A video tutorial on XXX", despite the actual user manual having step-by-step instructions complete with screenshots and usually more than one worked example.
What gets me is you are looking at an application and you see something like: DRsV Retention Period = 1
And you think "hmm, I wonder if that's 1 second, 1 minute one hour.."
You look in the 'help' which says: "DRsV Retention Period is used to set the DRsV retention period."
... and that's it! Nothing else, no explanation, no clarity. It just tells you what you already knew. It doesn't even tell you what the hell DRsV stands for (which I made it up).
You end up wondering why the person who wrote it even bothered.
It's because that's how he learned to comment his code : put in writing what any moron can see the code is doing.
When I give programming courses, I always harp on code commenting at some point, and when I do so, I give specific examples of what commenting should be. Don't tell me that you are offsetting to position r,c - I can see that in the code, you dolt.
Tell me that you start in the first cell of the table, and then you offset to the current position defined by the r and c loops that are in the sub that called this function. THAT is a useful comment because it tells my why the hell you offset when you have already set the cell you could logically be wanting to work on.
A useful comment tells me why you wrote the code so I don't have to waste an hour or two figuring it out on my own. A useless comment tells me something I can deduce three seconds after having read the code that is being commented.
Writing useful comments, just like writing useful documentation, is apparently something that requires more brain cells than the average developer has.
"Writing useful comments, just like writing useful documentation, is apparently something that requires more brain cells than the average developer has."
Is it lack of brain cells or (general) lack of guidance?
"The Elements of Programming Style" (Kernighan, Plauger) may be dated in its use of FORTRAN examples (and some others even more obscure) but the principles still apply:
3page highlights at:
http://ww2.cs.mu.oz.au/~zs/comp20006_2010_s2/resources/style.pdf
One it's arguably missing is "We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil" (attributed to Knuth or Hoare). But then again, Kernighan and Plauger's first principle is
"Write clearly -- don't be too clever" -- which probably covers premature optimization.
I don't use many "apps" on mobile phones. Unfortunately, skype is one of the few. Not only is its fucking user interface near incomprehensible but also fucking different on two different phones. How difficult must it be to fuck up a GUI for such a simple fucking application?!
(Sorry for the use of f-words. But I know how to develop software, testing, usability labs etc. And not just from reading books. It makes me fucking angry to see such rubbish.)
As far as I've been able to tell, the various Skype teams did their own thing with little in common other than the protocols and a general corporate look. I've used Skype across almost all platforms almost since the start and the UI is actually more consistant than it used to be, but still confusing, odd and subject to changing without warning.
I remember once reading an old (paper) magazine article (*) discussing alternatives to version numbers for indicating the increased functionality in new releases of software. One of the suggestions was to use the weight of the manual as a measure. Now if only that suggest had been adopted we'd not be having a problem with lack of manuals.
(*) I've a hunch it may even have been an Alistair Dabbs article - did he used to write for PC Plus? My memory is fuzzy on such things.
"One of the suggestions was to use the weight of the manual as a measure."
I used to work with a company doing safety critical software. Documentation was a key deliverable. One of the ways one particular supplier used to increase their quality (ie tonnage) was to include a complete copy of the assembly language users guide for the processor in question. Their software design was still carp though.
My favourite password technique, is the use of registration numbers of vehicles I have owned. A bit male brain spectrum maybe but it works for me and as historic biometric info, it's very private.
It's also easy to extend into more secure formats each of which is restricted to certain types of account
Low Level reg no only Discussion sites only eg El Reg
Mid Level reg no + trim Model range of vehicle or engine size.. Personal detail sites; Facebook
High Level reg no + Colour Money access sites; EBay
With the option of creating a personal recipe by interleaving the elements to your own choice,
two characters of colour, the reg no, rest of the colour. Or whatever takes your fancy and sense of paranoia
The real beauty of a scheme like this is you can write the hint down on plain paper "my first Mini" and the nature of the site determines which enhancement, if any you need to use..
Needless to say my Banking sites etc use a different stronger scheme.
Then you find that this site says you can not use a password because you used it on that site ten years ago.
Then the other site says you can not use that neat, 8 letter password you want to use for all the twenty you must change because they are 12 days old and have expired, because the password rules for this site say it must be only 6 letters or digits, while the others insist on at least one capital, number and punctuation character (no, not that one, silly, not in our list). Now you've got a dozen server, workstation and secure website addresses, all in the one firm (your apparent employer) with, seemingly, two dozen different rules and endlessly different expiration periods and restrictions against dictionary words … and you must not have used any of them before, ever. Then you get some asinine instruction, that you must never write down or record anywhere your passwords.
My wife was given an initial password yesterday, for a hospital system to cover web, sharepoint and email, that she should change immediately. However, this password, printed beautifully in a letter, contains "l" (ell?), or is that "I" (eye")?) and a nicely ambiguous "O", in three places. We tried writing down and entering every combination - no luck or probably silently locked out for trying too often.
Then one banking site wants a secret word (with its own set of permitted and required characters and length) from which it simply asks for the nth, mth and yth character; the next wants to send you an sms with a number. Of course, your battery just went flat; you left the mobile behind somewhere; it takes so long to find it the number has expired … then, finally, you mistype it.
Read more science fiction! If you can't find enough weird names that can then have (additional) punctuation added, then you aren't reading the right books! I find Iain M Banks books, between Culture citizens (especially drones), aliens and planets, serve me very well for now.
I'm using tomeCMS for documentation for a project I am working on. It's a bit basic (it is free) but lets me put a reasonable manual online quickly, edit and add to it when I need to, easily add code snippets or file downloads and so on. Unlike PDFs or word docs, you don't need to keep producing new files and uploading them for minor changes.
We once paid somebody to write a translatable and searchable Help system.
They did it (badly) in VB.Net 1.1 and never actually gave us the "final" source code, despite that being part of the contract.
At some point I'll have to bring the tool in house, but we just don't have the time for the complete, ground-up rewrite necessary just to add PNG support!
The problem with meaningless icons is down to recent designer fashion that decreed that representations of real-world objects or symbols were holding back the progress of the digital society.
That *might* make sense if all your software comes from one source with a consistent set of icon designs, so I guess it reflects the walled-garden aspirations of our current crop of major software producers
Back in around Oracle 6 and 7, Oracle would send out three or four feet of documentation with every sub-release. The documentation was quite good, but it did pile up. Add that to PeopleSoft documentation for v. 6 and v. 7, and presently you would have a tall shelf full of paper, much of it documenting modules you didn't know or care about. Yes, yes, recycling, but somebody has to haul it.
But then I find Oracle's 11g HTML documentation a nuisance and use the less obnoxious 10g documentation where possible.
Sadly no one (producers) wants to pay for documentation anymore. They assume that the bright spark 'designer' has made it so intuitive that just looking at the startup screen tells you everything you will ever need to know about the product. Of course its made worse by guys saying they never read the instructions, so why bother having them, so you have yourselves to blame.
It gets worse. I know of one open source project which hasn't updated its official documentation in years (although it's still willing to sell the outdated manual) which turned down an offer of free assistance from someone who writes software and hardware documentation for a living, because the guy officially in charge of documentation was "almost ready to restart rewriting the documentation". That was 3 years ago and he still hasn't started.
and more recently OS X Server told me it couldn't offer any help because "You are not connected to the internet".
Quite apart from the fact that not everyone has a 100% reliable internet connection, how the hell are all those non-Geeks who just want to set up a home network going to cope when they mess up their networking / OS X Server throws a wobbly itself*?
* delete as applicable.
Back in the "bad old days" of VMS one of my jobs was inserting the updates in the manuals every month - I think there was a whole bookcase full to do (and another one for the PDP11 manuals that we never used 'cause the system wasn't turned on but that had to be updated in case we were audited).
Now I usually bypass the vendor's help completely and go straight to Google.
When I was deputy CTO in a large international IT company, my mantra was "No Manual, No Software". Now I'm retired. I am trying to learn how to build websites using things like Laravel and Yii, but even buying the books recommended hasn't helped, so I am giving up. It was what made me give up on Joomla% and all the other wonderkind software goodies. No way IN. OK, if you know how to use them you can refer to reference stuff that helps with detail, but there is no damned overview way IN. I'm sorry folks, a YouTube Video doesn't hack it either.
Now, it's true that I am seriously old now, 64, so you can't expect me to call you U. But U have not written ANY software if you have not written the USER Manual.
"But U have not written ANY software if you have not written the USER Manual."
totally agree and would add:
But U have not designed ANY software if you have not written the Specification and High-Level Design Guide.
As a designer of IT systems, this the main reason why I've tended to avoid using open source - I don't have the time and my client's don't pay me, to mess around with the code.
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
