back to article 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 …

COMMENTS

This topic is closed for new posts.
  1. hammarbtyp

    I feel your pain...

    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.

    1. T. F. M. Reader

      Re: I feel your pain...

      Hmm... In my experience problems like that are usually resolved by enabling cookies till the end of the session. Never saw this in any manual though.

    2. Anonymous Coward
      Anonymous Coward

      Re: I feel your pain...

      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.

      1. Sherrie Ludwig

        Re: I feel your pain...

        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.

  2. Alistair Dabbs

    And it's especially fun when, having highlighted in red a problem with your registration, it empties all the form fields and resets all the options to their default so you have to start all over again.

    1. Anonymous Coward
      Anonymous Coward

      "empties all the form fields"

      Or leaves them all alone except for one, which you have to track down and re-enter. It isn't always the code on the back of your credit card, either.

    2. Steve Davies 3 Silver badge
      Boffin

      Spot on.

      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)

      1. PJI

        Re: Spot on.

        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.

        1. Kubla Cant

          Re: Spot on.

          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".

          1. Anonymous Coward
            Coffee/keyboard

            Re: Spot on.

            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>

          2. tony2heads
            Paris Hilton

            Manuals

            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.

          3. Phil O'Sophical Silver badge

            VMS manuals

            I think I read about 60% of them.

            I read them all. Used to impress the hell out of my colleagues when they asked me how to do something and after a moment's thought I'd send them to "Chapter 3 or maybe 4, volume 5a".

            OK, so maybe now that seems a little geeky... :)

      2. Simon Harris

        Re: Spot on.

        "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!

        1. Wensleydale Cheese
          FAIL

          Re: Spot on.

          "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.

        2. Angol

          Re: Spot on.

          ... 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.

      3. BongoJoe

        Re: Spot on.

        Dcumentation? I remember the old Microsoft C (before the days of Visual Studio) when the documentation came in a box four feet long.

    3. S4qFBxkFFg

      Especially when the "problem" is only due to the idiot web designer using an email validator written by an idiot developer who clearly did a tl;dr on the relevant RFC (assuming they even knew such things existed).

      + signs are valid in email addresses.

      Morons.

      1. Nick Ryan Silver badge

        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.

        1. Anonymous Coward
          Anonymous Coward

          Re: spaces in credit card number

          Space in credit card number are bad enough.

          The forms which spew a validation error when I put a space in my postcode, numberplate or phone number are worse.

          It isn't difficult to strip out spaces!!

          1. Simon Harris

            Re: spaces in credit card number

            Space in credit card number... postcode... are bad enough....

            Specially when they leave you to guess whether you should take out the spaces or not.

          2. Wensleydale Cheese
            WTF?

            Telephone numbers too!

            "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!

            1. Phil O'Sophical Silver badge

              Re: Telephone numbers too!

              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.

            2. bristolmoose
              FAIL

              Re: Telephone numbers too!

              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.

            3. Roland6 Silver badge

              Re: Telephone numbers too!

              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.

          3. Kubla Cant

            Re: spaces in credit card number

            Just yesterday I fell foul of a form that objected when I entered my card expiry date as "dd/mm" (the way it's written on the card) rather than "ddmm".

            Grrr!

          4. Allan George Dyer

            Postcode? Re: spaces in credit card 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?

          5. Anonymous Coward
            Anonymous Coward

            Re: spaces in credit card number

            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).

        2. MJS

          Totally. And it is much easier to transcribe four groups of 4 digits, especially when the 16-digit concatenation has multiple repeats.

        3. John Smith 19 Gold badge
          Unhappy

          "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.

          1. Simon Harris

            "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.

          2. Anonymous Coward
            Anonymous Coward

            Actually MICROSOFT had this -- for entering product keys. The cursor would jump by itself to the next field, so it was easy to enter the number in groups.

            But maybe they have a patent on it so nobody else is allowed to do it.

      2. JimmyPage Silver badge
        Unhappy

        + signs are valid in email addresses.

        so are apostrophes, as I discovered when a "O'Connell" tried to register in a program I once inherited.

        1. AOD

          Re: + signs are valid in email addresses.

          @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.

          1. rhydian

            Re: + signs are valid in email addresses.

            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...

      3. Anonymous Coward
        Anonymous Coward

        re: Email address validation

        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.

      4. BongoJoe

        Other moronic assumptions:

        - All houses have house numbers or street names.

        - That I can find my county in a list of dropdowns which was accurate only up until 1972

        - Pigeon holing my job as in Forestry, Accounting, Insurance, etc..

      5. Phil O'Sophical Silver badge

        + signs are valid in email addresses.

        And in phone numbers, but few US-based web sites can handle them.

        We don't hall have a "State" in our address either.

      6. David Beck

        Here here

        I am now the proud? owner of four email addresses for TomTom since I manage the family's four GPS boxes.

        1. TomTom allow one account to manage one GPS

        2. TomTom do not allow "+" convention in the email address

        Morons^2

      7. Ken Hagan Gold badge

        Re: + signs are valid in email addresses.

        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.

  3. Ian 55

    I still have some old Borland manuals

    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.

    1. Nick Ryan Silver badge

      Re: I still have some old Borland manuals

      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 :)

      1. Pascal Monett Silver badge

        I totally agree. Looking at my DOS 1.0 manuals I got with my (now defunct) IBM PC back in the day, I have to say that I await eagerly the day where I will find another supplier manual with that level of quality and dedication to the subject.

      2. Anonymous Coward
        Anonymous Coward

        Re: I still have some old Borland manuals

        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...!

      3. Simon Harris

        Re: I still have some old Borland manuals

        "The older the software/manuals, the better the manuals were."

        Can't agree more!

        The manuals for my first computer came with complete circuit diagrams, memory maps, operating system call vectors, the lot!

    2. silent_count

      Re: I still have some old Borland manuals

      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?

      1. Ken Hagan Gold badge

        Re: (This sort of stuff is why non-tech people only use the admin account! )

        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.".

  4. Anonymous Coward
    Anonymous Coward

    "no software company or its customers could reasonably afford these days"

    At £400 for the full version of Office and over £3000 for an SQL Server licence, I think Microsoft could afford a proper manual.

    1. Not That Andrew

      Re: "no software company or its customers could reasonably afford these days"

      I notice that Microsoft Press seems to have become a division of O'Reilly. And talking of O'Reilly, what happened to the The Register's BOFH O'Really T-Shirts, like Distributing Clue To Users.

    2. Anonymous Coward
      Anonymous Coward

      Re: Microsoft could afford a proper manual.

      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?

      1. Richard 12 Silver badge

        nnnn nnnn nnnn nnnn

        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.

        1. Anonymous Coward
          Facepalm

          Re: nnnn nnnn nnnn nnnn

          nnnnnnnnnnnnnnnn.

          Yes. It was a joke

    3. Anonymous Coward
      Anonymous Coward

      Re: "no software company or its customers could reasonably afford these days"

      "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/

  5. JimmyPage Silver badge
    Thumb Up

    I had to post, to salute the title ..

    "Manual Stimulation", fnarr fnarr

  6. Reginald Marshall

    Unsurprising

    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.

  7. Tom7

    Video tutorials

    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!

    1. WraithCadmus
      Unhappy

      Re: Video tutorials

      This seems to go double for Minecraft mods, where the developer often refuses to provide _any_ text-based docs.

    2. Alistair Dabbs

      Re: Video tutorials

      They say developers can't write. Unfortunately, it's also true that IT trainers (who are responsible for most of these video tutorials) can't speak.

      1. Anonymous Coward
        Anonymous Coward

        Re: Video tutorials

        "developers can't write" - we should be so lucky. Most developers can't even code. Otherwise there wouldn't be the deluge of patches.

    3. This post has been deleted by its author

    4. Intractable Potsherd

      Re: Video tutorials

      "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!

  8. Tom 7

    And dont do it in paper format!

    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.

    1. Nick Ryan Silver badge

      Re: And dont do it in paper format!

      Definitely with you on the video. It's useful for some things, but many guides would be far better served as text as images so you can take it at your own pace, in an office, without blaring out random adverts and drawling voices all the time.

      1. Richard 12 Silver badge

        Video tutorials are an odd one

        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.

  9. Herbert Meyer

    for the illiterate, by the uninterested

    Remember RTFM ? My experience was the users (or the tech support drones) would call me up, and ask me to read the manual for them.

    1. Alistair Dabbs

      Re: for the illiterate, by the uninterested

      So what do you say now? 'Aimlessly Research Some Explanation - Web Internet Promises Everything'?

  10. Aaiieeee
    WTF?

    Why bother..

    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.

    1. Pascal Monett Silver badge

      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.

      1. Anonymous Coward
        Anonymous Coward

        "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.

  11. Evil Auditor Silver badge
    Stop

    Skype

    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.)

    1. cyclical

      Re: Skype

      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.

  12. Pascal Monett Silver badge
    Happy

    "pharcical phucking phanboi phondleslab"

    Phabulous !

    1. Alistair Dabbs

      Re: "pharcical phucking phanboi phondleslab"

      Phank you.

    2. AbelSoul

      Re: "pharcical phucking phanboi phondleslab"

      Phantastic.

  13. stucs201

    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.

    1. Ken Hagan Gold badge

      Re: weight of manuals

      It would also mean that everything you download off the internet was labelled as version 0 -- which isn't too far off the truth.

    2. Anonymous Coward
      Anonymous Coward

      weight of manuals

      "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.

  14. kmac499

    Password generation

    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.

    1. Pascal Monett Silver badge
      Trollface

      Re: Needless to say my Banking sites etc use a different stronger scheme

      Doesn't make a difference. You have a FaceBook site therefor all your banking details are belong to them.

    2. PJI
      Flame

      Re: Password generation

      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.

    3. Fading
      Facepalm

      Re: Password generation

      Nope all my passwords are now "correct horse battery staple" as it's the only one I can remember....

      Thank you XKCD!

      1. Intractable Potsherd

        Re: Password generation

        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.

  15. Anonymous Coward
    Anonymous Coward

    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.

    1. Alistair Dabbs

      tomeCMS

      What, that 'open source' system that's dependent on Microsoft's Windows Server platform? Hmm.

      1. Anonymous Coward
        Anonymous Coward

        Re: tomeCMS

        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!

  16. arrbee

    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

  17. disgruntled yank

    Yes and no

    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.

    1. Anonymous Coward
      Anonymous Coward

      Re: Yes and no

      That's because Oracle, like most other hi-tech companies, have "saved money" by laying off half their technical writers, and now expect the developers to write whitepapers, FAQs and howtos in their copius free time, instead.

  18. Anonymous Coward
    Anonymous Coward

    WFW 3.11 + DOS

    I remember my first PC, a 486, came with a weighty tome which was the manual for DOS 6.22, Windows 3.1 and Workgroups 3.11.

    It covered everything, from batch files to control panel to setting up local network post offices...

  19. Alistair
    Coat

    Documentation

    The best "how to" documentation I've ever seen was the blue on white manual that shipped with my minix disks.

    /ducks and runs

  20. sandman

    Xara

    Those nice people still send out paper manuals (at least for the Designer Pro software) - even when you purchase the download version :-)

  21. Bryan Maguire

    When i started my first programming job i was given the manuals for Microsoft Visual C++ V1.5 for Windows. All 4 feet high of them.

    1. Roland6 Silver badge

      Re: All 4 feet high of them.

      The laugh is that the original C++ language reference was a circa 60 page document that assumed you had a working knowledge of Kernighan and Ritchie, a centimetre thick book.

  22. Faye B

    Wot no manual!

    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.

    1. Ken 16 Silver badge

      Agile

      It's RAD - best thing since sliced bread, haven't you heard?

  23. Not That Andrew
    Facepalm

    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.

  24. PerlyKing
    Unhappy

    Online help

    My (least) favourite "online help" experience was troubleshooting a connectivity problem on (you guessed it) Windows. Having tried a couple of things locally, it decided to search online to find out how to solve the problem.... Finally solved by rebooting, obviously.

    1. Wensleydale Cheese

      Re: Online help

      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.

  25. GlenP Silver badge

    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.

  26. TheOldFellow

    No User Manual, no software.

    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.

    1. Roland6 Silver badge

      Re: No User Manual, no software.

      "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.

      1. Ken Hagan Gold badge

        Re: No User Manual, no software.

        "this the main reason why I've tended to avoid using open source"

        Does that mean you prefer to use closed source because in that case you can't see that they didn't have a spec?

        1. Roland6 Silver badge

          Re: No User Manual, no software.

          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).

  27. Darryl
    Thumb Up

    Help!

    I don't bother with most of the "help" systems written into software anymore. Honestly, the easiest way to find out how to get software X to perform operation Y is to Google 'How do I get X to do Y'

  28. Kubla Cant

    Illiteracy

    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.

    1. MJS

      Re: Illiteracy

      Thank you. I'm so glad I'm not the only icon-hater. And no, I won't 'Add an Icon' to this comment.

  29. DwarfPants

    Ranting

    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.

  30. JLV

    Name & shame.

    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.

    1. Anonymous Coward
      Anonymous Coward

      Re: Name & shame.

      vimtutor is your friend.

  31. Blitheringeejit
    Unhappy

    You think you're having a bad time...

    ...not getting manuals with your software. How do you think I feel - I used to earn a decent living writing the bloody things. I'm a relic of a bygone age.

    1. Ken Hagan Gold badge

      Re: You think you're having a bad time...

      Most UIs these days are so badly designed that it would turn you into a swivel-eyed loon if you actually documented it in any detail. So ... you've been spared that fate, at least.

    2. Alistair Dabbs

      Re: You think you're having a bad time...

      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.

  32. Mike Moyle

    As an ex- tech pubs* guy...

    ...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!)

    1. Sean Timarco Baggaley

      Re: As an ex- tech pubs* guy...

      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!"

  33. JLV

    be careful what you wish for...

    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?

    1. Anonymous Coward
      Anonymous Coward

      Re: be careful what you wish for...

      What you may have missed (presumably) is that once you read the entire documentation set, you'll know how, and more importantly, why to do things using the software.

      Hooray, I can edit my potss.

      1. This post has been deleted by its author

  34. lglethal Silver badge
    Joke

    Douglas Adams had it right

    Every true manual should start with the following words in large, friendly letters on the cover:

    DON'T PANIC

  35. hairydog

    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!

    1. Alistair Dabbs

      >> Users can't be bothered with learning how things work

      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.

  36. John Smith 19 Gold badge
    Unhappy

    *Properly* written user documentation is *tough*.

    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.

    1. Anonymous Coward
      Anonymous Coward

      Re: *Properly* written user documentation is *tough*.

      "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.

  37. Herby

    Yes, Virginia, Documentation is Hard!!

    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.

  38. Anonymous Coward
    Anonymous Coward

    It's the logic of the market, innit

    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...)

  39. Brewster's Angle Grinder Silver badge

    I can see a gap in the market for a new book: Manual Writing For Dummies.

  40. J.G.Harston Silver badge

    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).

  41. J.G.Harston Silver badge

    Video how-tos

    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?

    1. Ian 55

      Re: Video how-tos

      You don't get the ad revenue.

  42. a_yank_lurker

    Manuals and other stupidities

    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.

    1. Alistair Dabbs

      Re: Manuals and other stupidities

      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.

    2. J.G.Harston Silver badge

      Re: Postcode expansion

      Some websites that accept UK addresses have become intelligent enough to ask for house number + postcode then expand it to a full address with a 'is this correct?' prompt.

      1. BongoJoe

        Re: Postcode expansion

        Alas most of these aren't too intelligent to understand that not everyone is fortunate to live in a propery which doesn't have a number or a street name.

  43. Sureo

    Manual stupidities

    I recently bought a gadget that came with a 50 page manual. The manual was 1 page long, and came in 50 languages. I can see where the manufacturer may have been coming from, but the box and the install program were both in English.

    1. Anonymous Coward
      Anonymous Coward

      Re: Manual stupidities

      " 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).

  44. John Smith 19 Gold badge
    Unhappy

    And in case you were wondering....

    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)"

  45. Martin H Watson

    Web sites that insist on a mobile number when I actually don't have one really bug me. Nearly as much as free Wi-Fi that wants to send a code to my non existent mobile. Or perhaps I'm using free Wi-Fi because my mobile has died.

    1. J.G.Harston Silver badge

      My mobile number is 0000 000-0000.

      Or 0000 000 0000, 00000000000, 0700 000 0000 or 07000000000 depending on how much the site checks the number.

  46. Stuart Castle Silver badge

    Not only help systems..

    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..

  47. M7S

    "keepass"

    why, are you in danger of losing yours?

  48. Anonymous Coward
    Anonymous Coward

    Just bought a new laptop…

    …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.

  49. Sarah Balfour

    Y'know what REALLY grinds my gears...?!

    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!

This topic is closed for new posts.

Other stories you might like