53 Comments
Jun 2, 2023Liked by Alistair Dabbs

Showing my age but I had a BBC Micro which came not only with a massive manual but even had a fold out circuit diagram in the back of it. My first PC ran MSDOS 4 and despite being only 2 3.5" floppy discs had a manual the size of the phone book with it detailing every command and parameter you could think of.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

HP 3000, 17 (iirc) 3" ring binders.

Windows 3 SDK, 3 3" thick books

Ah, the good old days

Expand full comment

I, still have several shelf fulls of such. And the related hardware. From previous articles I suspect I'm not the only one.

Perhaps a century from now some budding IT archaeologists will be able to use all of our hoarded kit and manuals to gain insights into the technology of the past 50 years or so :)

Expand full comment
Jun 2, 2023·edited Jun 2, 2023Liked by Alistair Dabbs

As a software designer/developer/publisher myself I am 100% with you on this one. No questions asked!

However, if you ask the yoof, they will tell you 'If it ain't a YT video, it don't exist'

Even this very day, nay not 2 hours ago, a young gentleman informed me that his dream job was to be a software developer but he was not, ever, going to read anything like documentation.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

well that will be good quality code (not)

Expand full comment
Jun 2, 2023·edited Jun 2, 2023Liked by Alistair Dabbs

I'll leave it to your imagination what my response to him was, especially regarding his chances of ever getting a job

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

Sadly, this does not seem to have much effect - especially on the user interface designers!

Expand full comment

We'll all be replaced by some AI chatbot soon, allegedly.

I did send a link to the wiki page for "The Last One" to one of my keener colleagues recently...

Expand full comment
Jun 4, 2023Liked by Alistair Dabbs

I thought YT was old hat these days. If it's not Instagram, TikTok or a bloody "podcast" then it's the equivalent of stone and chisels.

Expand full comment
Jun 4, 2023Liked by Alistair Dabbs

I find it extremely concerning that whatever the preferred method of learning may be if it does not include RTFM then it does not bode well for anyone

Expand full comment

Absolutely!

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

I like writing documentation myself. And insist on step by step instructions with copious amounts of screenshots and more importantly notes to say if you try to do it this way it will fail. Having had said process fail until I found out why (usually a mistranslation that causes confusion).

Mainly for two reasons one it helps others out, and two by the time I come back to looking at it in 6 months time I won't have a clue how to do it myself as I will have forgotten.

But yes manuals the wonderful set of instructions on how to fix stuff or work with it, I can remember starting work using Autocad 10 and there were 2 nice thick manuals with all the command references in them. Phone Systems and server documentation you could sit down and read (and more importantly stick notes in to find stuff quickly). I will still find the pdf version and shove it through a printer so I have something to refer to - especially for the mounting instructions for a machine which do not want to be online when you are installing it.

There is one company that produces very detailed manuals for its products still - Lego.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

That is a good one, installing an operating system which is constantly referring you to online documentation which you cannot access because you are trying to install the damn operating system so you can access the internet

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

Yes, although I remember on the Commodore Amiga 500 there was an introduction disk included - which had the instructions on how to connect the computer up....

Expand full comment
Jun 2, 2023·edited Jun 2, 2023Liked by Alistair Dabbs

Another classic is the 'How to repair/upgrade your computer hardware' YT videos, which you cannot watch whilst you are trying to repair/upgrade your computer

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

A MacPedant writes: I don't think the Bard would have had much luck getting hold of any Union Jacks, let alone selling them

Expand full comment
author

He may have seen one on the boat as he headed south to Spain.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

MacPedant mansplains: a Great Britain flag, maybe, but not a Union Jack ( no Ireland )

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

Chances are even the Bard of Stratford himself arriving in Spain sporting a Union Jack (or indeed the flag of Great Britain) would have been burnt at the stake within 30 minutes of his landing making the whole point somewhat moot.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

I once worked for a company that decided to put all its product documentation into their internal conference system so that all the developers, marketing, support etc could "keep it upto date". Each contents section would be tagged with the kind(s) of user/internal doc it should used for, so at release time creating a new set of docs would be little more then pressing a button and having the contributors review the results.

Turned out that involving 40+ people with overlapping senses of ownership and non-overlapping opinions did not speed up the production of the final documentation.

Expand full comment
Jun 2, 2023·edited Jun 2, 2023Liked by Alistair Dabbs

Ah the classic too many cooks problem.

Much easier to have someone write the document - one other person to review it and then everyone else has to use it.

It is the same principle with meetings as the number of participants (victims) increases the chances of an agreement diminish to nothing...

Expand full comment
author

This is the principle of a wiki, isn't it? And the title of the wiki page is "My favourite colour"...

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

Bob just corrected that to: "My favorite color"

Alice changed it to "Our preferred color" as she thinks it looks more professional

Chuck modified it to "Our preferred shade" to avoid transatlantic spelling issues

Gordy the Goth deleted the whole page because the answer is obviously black

Expand full comment

And the Janitor, who for some inexplicable reason has write access to the wiki page, just wrote

'Que'

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

Oh for heaven's sake everything is in "man man":

MAN(1) Manual pager utils MAN(1)

NAME

man - an interface to the system reference manuals

SYNOPSIS

man [man options] [[section] page ...] ...

man -k [apropos options] regexp ...

man -K [man options] [section] term ...

man -f [whatis options] page ...

man -l [man options] file ...

man -w|-W [man options] page ...

DESCRIPTION

man is the system's manual pager. Each page argument given to man is

normally the name of a program, utility or function. The manual page

associated with each of these arguments is then found and displayed. A

section, if provided, will direct man to look only in that section of

the manual. The default action is to search in all of the available

sections following a pre-defined order (see DEFAULTS), and to show only

the first page found, even if page exists in several sections.

The table below shows the section numbers of the manual followed by the

types of pages they contain.

1 Executable programs or shell commands

2 System calls (functions provided by the kernel)

3 Library calls (functions within program libraries)

4 Special files (usually found in /dev)

5 File formats and conventions, e.g. /etc/passwd

6 Games

7 Miscellaneous (including macro packages and conventions), e.g.

man(7), groff(7)

8 System administration commands (usually only for root)

9 Kernel routines [Non standard]

A manual page consists of several sections.

Conventional section names include NAME, SYNOPSIS, CONFIGURATION, DE‐

SCRIPTION, OPTIONS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT,

FILES, VERSIONS, CONFORMING TO, NOTES, BUGS, EXAMPLE, AUTHORS, and

SEE ALSO.

The following conventions apply to the SYNOPSIS section and can be used

as a guide in other sections.

bold text type exactly as shown.

italic text replace with appropriate argument.

[-abc] any or all arguments within [ ] are optional.

-a|-b options delimited by | cannot be used together.

argument ... argument is repeatable.

[expression] ... entire expression within [ ] is repeatable.

Exact rendering may vary depending on the output device. For instance,

man will usually not be able to render italics when running in a termi‐

nal, and will typically use underlined or coloured text instead.

The command or function illustration is a pattern that should match all

possible invocations. In some cases it is advisable to illustrate sev‐

eral exclusive invocations as is shown in the SYNOPSIS section of this

manual page.

EXAMPLES

man ls

Display the manual page for the item (program) ls.

man man.7

Display the manual page for macro package man from section 7.

(This is an alternative spelling of "man 7 man".)

man 'man(7)'

Display the manual page for macro package man from section 7.

(This is another alternative spelling of "man 7 man". It may be

more convenient when copying and pasting cross-references to manual

pages. Note that the parentheses must normally be quoted to pro‐

tect them from the shell.)

man -a intro

Display, in succession, all of the available intro manual pages

contained within the manual. It is possible to quit between suc‐

cessive displays or skip any of them.

man -t bash | lpr -Pps

Format the manual page for bash into the default troff or groff

format and pipe it to the printer named ps. The default output for

groff is usually PostScript. man --help should advise as to which

processor is bound to the -t option.

man -l -Tdvi ./foo.1x.gz > ./foo.1x.dvi

This command will decompress and format the nroff source manual

page ./foo.1x.gz into a device independent (dvi) file. The redi‐

rection is necessary as the -T flag causes output to be directed to

stdout with no pager. The output could be viewed with a program

such as xdvi or further processed into PostScript using a program

such as dvips.

man -k printf

Search the short descriptions and manual page names for the keyword

printf as regular expression. Print out any matches. Equivalent

to apropos printf.

man -f smail

Lookup the manual pages referenced by smail and print out the short

descriptions of any found. Equivalent to whatis smail.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

This is why I hate linux / unix help pages

Expand full comment
author

I had a dream like that.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

Isaac Asimov once dashed off (literally) a short-short story in which his protagonists were dealing with devices that came with incomprehensible assembly instructions. They were awaiting the delivery of a robot that would do all the assembly work - only to find that it came in bits with incomprehensible assembly instructions.

In "Zen and the Art of Motorcycle Maintenance" the author points out that the job of writing manuals is usually given to the least capable member of a team because the people who know what they're doing are too busy.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

one of my favourite Asimov stories

Expand full comment
Jun 4, 2023·edited Jun 4, 2023

"the author points out that the job of writing manuals is usually given to the least capable member of a team"

That book was written in 1974 and nothing has changed since. Except, perhaps, the 'reason' ("the people who know what they're doing are too busy") - which might be the _given_ reason but it's definitely not the _actual_ reason, which is either that they are too self-important to be bothered or are simply incapable of explaining anything to anyone who isn't at least at their level of geekiness, and can speak only in technobabble.

Expand full comment
Jun 5, 2023Liked by Alistair Dabbs

As a newly-qualified graduate in my first 'proper' job, I was given the task of reviewing a product Sales Manual recently produced for use by our representatives around the world. This was quite a big tome, company-confidential with lots of useful references and handy technical information.

But it was riddled with serious errors including formulae using maths closer to myths, material properties which defied physics and 'helpful' conversion factors that were wrong. In all there were about fifty pages of jaw-dropping cock-ups.

When I pointed this out, the response was "Oh, don't worry. No-one will read it."

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

Microsoft help files: "You can do this! And this! And this! And for more info follow this link...." leading to another page that says "You can do this! And this!...." until finally you arrive at a page that has nothing to do with your original query.

Microsoft docs are accurately unhelpful. Linux docs are comprehensively incomprehensible.

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

I'm trying to remember when I gave up trying to find, much less make use of, help.

...

Drawing a blank. Maybe just before I binned my last Windows install? 2012 maybe? Then, after migrating to Ubuntu (quiet please, I can hear you laughing all the way over here) depending upon their community forums. Now, Google whatever my issue may be in the most precise terms I can find. Pick the most recent/salient link and explore. Good luck to me, I'm thinking I'll need it.

Expand full comment
Jun 2, 2023·edited Jun 2, 2023Liked by Alistair Dabbs

Amusing as these comments have been as usual, none of us have actually addressed Mr. Dabbs original question;

`Why doesn’t software come with instructions any more?'

Unfortunately I feel that the answer is all too simple;

'Because no one told the publishers it would be required'

Which is a very sad indictment on our industry.

Expand full comment
Jun 3, 2023·edited Jun 3, 2023Liked by Alistair Dabbs

Because in these days of “agile” (move fast and break things) by the time the documentation is written someone else will have changed the layout / functionality to bear no resemblance to the version that the author has just completed.

This is especially true in mobile apps which can be updated almost daily…

Expand full comment
author

Then change the documentation daily. It's not difficult. The resources to write text and take some screenshots or videograbs are miniscule next to those affording to tinkering with the product. It's just pure laziness born out of the self-delusion that their UX is perfect.

Expand full comment

Winging Programmer: why should I have to do this

Documentation Writer: Where is my baseball bat?

Expand full comment

Abso-fucking-lutely

90% of documentation is generated anyway, which is why it is crap but even crap documentation is better than none

Expand full comment
Jun 2, 2023Liked by Alistair Dabbs

"But these days, if I tap F1, the chances are that nothing will happen at all."

Being fair (?) to Microsoft, since the beginning of time you could press F1 in any Office program and be completely sure you wouldn't find anything even remotely helpful in the "Help" winow that took a minute to load and stole focus from whatever you were doing.

Expand full comment
author

But... but... no Clippy?

Expand full comment
Jun 3, 2023Liked by Alistair Dabbs

Ahh, how I love your weekly musings, we are all that “older person shaking their fists and yelling at the clouds”!

Nice to know we are not alone.

I also sense another musing on the placement of options under various menu items. My “favourite” is PowerPoint and the need to edit the slide master. Not under Edit, let’s try the Design menu, nope…. Oh yes, it is under the view menu. I don’t want to view it, I want to edit or design a new slide master….

Expand full comment
author

Adobe changed its products to use the word 'Parent' in place of 'Master' (guides, pages, etc). I thought it was a polite inclusivity change to minimise gender-specific terminology, but I was wrong. Apparently it was done to stop insulting descendants of victims of the Atlantic slave trade. Yes, really.

Expand full comment
Jun 4, 2023Liked by Alistair Dabbs

Oh yes, I heard that argument a couple of decades ago already, when referring to IDE drives that had to have a jumper set to be "master" or "slave".

Expand full comment
Jun 3, 2023Liked by Alistair Dabbs

The awards for .....

1. Best user manual goes to the Nortel Meridian series of PABXs. Step by step instructions for everything, in the correct manual for that topic. Frankly I could kiss the authors, they got me out of so much trouble.

2. Worst user documentation. In second place, most Linux installation write ups because they miss vital steps, except those from Digital Ocean which are brilliant. In first place, Microsoft 365 administrator online help. As punishment, Satya Nadella needs to do what Scott McNealey did at Sun Microsystems; install a 365 site from scratch one weekend, on his own with only the online documents for assistance. He’ll soon crack under the uselessness of it all. I once sat in a meeting where someone replied to my simple question with a full 30 seconds of speech, but none of the words made any sense at all! He’ll be right at home in Microsoft.

3. Best car UI. Volvo, no contest. Everything to hand that is needed, and everything else behind menus. Good to see VW have copied that, but $deity knows what Audi are up to with their full width dashboard, next they’ll be selling VR headsets.

4. Worst car UI. Honda Jazz. Was this designed by a bunch of students celebrating end of year having a laugh with rather too much alcohol? I don’t even know how to turn the radio on. To pair a phone over Bluetooth took a YouTube video.

Expand full comment
Jun 4, 2023Liked by Alistair Dabbs

I can with gratitude say I have never in my 63 years sat in the driver's seat of a Volvo because it could not possibly matter *HOW* good the UI is, nothing could possibly compensate for having to drive a Volvo.

Expand full comment
Jun 4, 2023Liked by Alistair Dabbs

Oddly enough, one of the best cars (or, at least, most fun) was a Volvo 240GLE. Rear-wheel drive, limited-slip diff, reasonably pokey engine, disc brakes on each corner (not common at that time), very comfortable seats. It was a very heavily armoured rally car,* especially with appropriate tyres for the weather. I had a girlfriend in Sale (Manchester) at the time, and I regularly did the journey over the Woodhead Pass in 45-50 minutes (late at night). My girlfriend managed it in 40 minutes, engine on to engine off, once. I know nothing about modern Volvos, but the 240 was brilliant.

*Indeed, there were some real 240 rally cars - impressive to watch.

Expand full comment
Jun 4, 2023Liked by Alistair Dabbs

I had a Volvo 740 once, I have to say it was the biggest heap of shit I ever owned, full disclosure, my father was a designer at Volvo

Expand full comment
author

There was an old pub joke: "Why are Volvos called Volvos? Because they're driven by c***s." Never could understand the joke as I'd never experienced a problem with Volvo drivers and I always thought the seats were comfy.

Expand full comment
Jun 5, 2023Liked by Alistair Dabbs

Gotta say I don't get that joke either. But perhaps the seats are too comfy thus inducing stupor in the driver, not really a condition I wish to see in my fellow road users

Expand full comment
Jun 4, 2023Liked by Alistair Dabbs

"articles that describe in general terms what functions exist in the software but without explaining how to use them"

Next best after this is the [excrucuatingly] detailed explanation of how to use feature _xyz_ without telling you which keystrokes, touches, fondles, or menu clicks it took to open it 😡😡

"My other pet hate is the shit-munching video tutorial"

Absolutely 100% yes. Comes from the same person who replies to your text messages with a voice note -

- 15 seconds of scratching, throat-clearing, and pocket noises

- followed by 10 seconds of umming and stuttering and explanations that it's 'easier' or 'quicker' to leave a voice note than to type on a phone

- followed by a long inarticulate (and indeed oftern largely incoherent) story, stopping and starting over and repeating and correcting and jumping back to the part where they said that other thing but before the part where you already got lost - and which you have to listen to several times before you even get the gist of it let alone the full meaning

- and all of it partly muffled when they put a finger over the microphone and partly drowned out when a lorry drove past their open car window and of course all accompanied by the radio in the background (if you're lucky, only music, but more often than not it will be a manic and probably coke-fuelled pop-station presenter)

Whew, I got a bit off topic there for a minute didn't I. What I'm trying to say is the people who use YT to give 'instructions' don't have the discipline to order their thoughts, the vocabulary to express them in the written word, or the patience to edit them into a succinct set of instructions. Plus, of course, a post to a support site or help forum *ISN'T MONETISED.*

Expand full comment
Jun 4, 2023Liked by Alistair Dabbs

you may have a point, I do so love the pennies that roll in every year from support contracts so producing crap documentation is actually in my best interest

Expand full comment
Jun 16, 2023·edited Jun 16, 2023Liked by Alistair Dabbs

Re: "So I called my accountant to ask what I should do next. He told me to ditch the half-arsed software I was using because it was shite. Good suggestion. That’s the kind of advice the developers should have put in their Knowledge Base."

Last time I consulted my accountant, he asked me for help using his accounting suite... I suggested the same your accountant suggested to you.

Expand full comment
author

He told me to use Sage.

Expand full comment