Tech support team won pay rise for teaching customers how to RTFM Welcome once again to On Call, The Register's Friday column that shares your stories of helping confused, caustic, and curmudgeonly customers to crank their computers into correct configurations. This week, meet a reader who we'll Regomize as "Marvin," who once held the title "field engineer" at a company that provided …
This post has been deleted by its author
huge stack of manuals
Way back in my first role at a government establishment (not a secret one) 40 years ago we ran a couple of DEC VAX minis (an 11/780 and an 11/750) plus we had an ageing PDP 11/45 that was never actually turned on (we couldn't dispose of it as part of the purchase for the VAXen was that they were compatible).
We had a whole bookcase filled with the manuals for the two different systems, all in ring binders, so once a month my job as the junior was to go through all the issued updates and addenda, removing the old pages and inserting the new ones. It wasn't exactly a difficult task but you had to be very methodical (I would always tear the redundant pages out so they couldn't be mixed up with the new ones).
Towards the end of my time there I also acquired a DEC Alpha (another load of manuals of course) and we installed an LN03 Laser Printer so I had my first exposure to word processing - great, I could type my own letters, print them out and send them to the typing pool to be retyped!
Ah, good times. I remember my first "real" job as a developer.
We had 1 bookcase full of the VMS (+DCL) manuals.
Another bookcase was filled with manuals for the development tools: Rdb, Cobol, Fortran, Pascal, Forms, Rally and some others I never touched.
But then the Web happened, and I never again opened another bookcase like that.
And then to the paperback White Wall.
I recall having a phone conversation with a DEC sales rep who wanted to know if we'd still purchase the hardcopy manuals since the CD-ROM versions were available. Since the CD-ROM version required multiple discs and we weren't rolling in cash to be able to have multiple CD-ROM readers on the system to keep the multiple discs online -- which meant skimming through multiple manuals entailed mounting/remounting different discs to track down a solution -- my response was that we'd still want one copy of the hardcopy manuals to avoid that hassle. The cost of the hardcopy version wasn't excessive as I recall. Anyway... this seemed to mystify said DEC rep who'd obviously never had to pore through multiple manuals opened to the appropriate pages to fix a problem.
The drawback to the White Wall was that updates required replacing the whole manual unlike the ring binder version.
huge stack of manuals
You missed out "about five feet (150 cm) in height" which in my experience must have been the abridged version. Many yards of manuals was more typical. A friend of mine had two desks in his office, one just for the manuals he needed open at any one time, and it was rarely enough.
I remember when we got our first IBM 3800-3 laser printer. Got the obligatory shelf of manuals for that Was tasked with creating some graphs for manglement, so was issued the shelf of GDDM manuals.
They all cross referenced each other across both products and multiple volumes in the set, but no clear starting point, and I ended up in a loop. I photocopied the relevant pages and put them in order, then rotating the point I started until it worked.
Then, our SE gave us a copy of the super secret red book which listed all the commands that the AFP generated, and I coded the graphs using those commands. Much simpler
Redbooks weren't secret, but you did have to know of their existence and how to ask for them.
But if you were an IBM account, you probably had access to Ehone (in Europe) or Hone for the US (these were systems accessed remotely, way before the Internet), or if you didn't, then your VAR or Account Rep. did, and all the redbooks were listed, and could be ordered through the normal documentation ordering system.
The whole point of redbooks was to make the technology more accessible, and redbooks were documented real-life experiences using the technology, written by teams made up of IBM product specialists, support representatives and customers. So often they acted as condensed cheat-sheets of the most useful features and commands necessary to get something working.
Back in the day when an IBM support agreement included How-To type questions, it often benefited the support teams to cope with the customer questions by actively pointing out the redbooks and making them available to customers. But sometimes, VARs kept the existence of redbooks hidden from their customers, to allow them to apparently add value, which could allow them to earn brownie points in their relationship with end-customers because of their 'expertise'.
The whole network of customers, agents, VARs and often different arms of IBM itself was of a tangled mess of conflicted interests, unfortunately.
When I first got into IT in the late 1980's you got loads of manuals and documentation which just piled up. Then you added binders from training courses and got a lot of paper on shelves and in cabinets.
By the time I neared retirement it was all gone as either everything was online / PDF, or I not longer did that stuff any more. Indeed by the end my entire presence in the company was my laptop and the backpack used to move it from place to place
You describe somewhat what is going on here. I had lots of books, and then it went digital. My mother had even more books, constant heavy lifting when moving. And now when counting digital I might have ten times as much than she and I ever had (hunter-collector genes are strong in this one), but the space is not a problem any more. The scans of comic/manga got beyond the 3000x5000 pixel range, with the 4500x8000 as next step already there, which is much better than any printed resolution could offer. A large TV as monitor or "ebok reader". I gave most of those books/comics/manga away, so others can have their reading fun, and I have more room for other hobby stuff. And I still prefer actual manuals, even when written as .HLP or .CHM, 'cause a consistent offline manual forces a better design. Now F1 sends you to the internet, and quite often to a dead MS-link or a search term in a search engine which answers with everything but helpful. Even worse with Artificial Incompetence.
I'm sure I read a story somewhere, possibly even on here, that the reason Novell provided a shelf-full of very visible (bright red more or less) manuals for Netware was because the software itself originally came on a single floppy disk.
IT had to be able to show something tangible to the bean-counters / senior management for the very large sum they had forked out just for the software.
NetWare 2.15 (pretty sure on that version but it was a *long* time ago, could a been 2.2) was provided, IIRC, on about 40-50 360K 5.25"disks and the install procedure after an excruciating disk test that could take *days* and fail in the last 0.1% was to compile and link the runtime according to your chosen options so, for the 360k version, there was a portion of the install which was like find the lady and if you cocked it up or needed to make changes like add a protocol or change network technology you got to start again.
Ask me how I know.
NetWare 3.12, one of my other expertise of the decade was on 3.5" disks, many of them, but was far easier to install and reconfigure after the fact.
Sorry, but the archives tell different number of disks. Netware lite and Personal Netware are closer to your numbers.
You could boil down the number of 720k disks needed if you knew ahead what machine, network cards and services were needed. Maybe that was your installation set, reduced to fit the machines you set up.
I have never used any version, but to try to answer the how many disks question, I found an archived image of NetWare 2.0 which consists of 13 360k 5.25-inch floppy disks. I'm not sure if that's the only option they had, but if you could use 3.5-inch disks to have fewer, then you could cut that to 8 720k or 4 1440k disks, either of which would probably make for a rather small package if trying to show someone clueless what a lot of money was spent on.
Not necessarily. On the same archive, the version 2.2 image consists of 19 1440k 3.5-inch floppy images. If those also shipped on 360k floppies, that could be almost 80 of those. Any number you may state can be backed up by some of these versions. It seems they added a lot of something between 2.0 and 2.2.
Read The Friendly Manual
*Then* come back to annoy the dev who is getting less friendly by the minute (but isn't allowed to *quite* say what he is thinking by this point; what is that grinding noise?)
(Had a ThinkGeek mug marked RTFM on my desk - often pointed at me when the compiler objected at my syntax - because they never did a "No, I am not a tier 1 help desk" mug)
Last century I recruited a replacement Manufacturing Manager to work with my design team, and I was so keen to get someone started to help with the workload that I neglected to listen to my inner voices. The guy got the job purely because he attended the same (engineering) university as me, so he must be good. Right? Right?? Of course reality dawned rather quickly, and I was left to work with with someone who was completely hopeless in the real world. Paper qualifications may imply one thing, but actions speak so much louder; He was always asking for help with even the simplest of tasks, and my patience was worn down on a daily hourly basis.
The final straw came on the fateful day when he asked me how to format some superfluous procedural document, to which I simply said "Richard, RTFM"
As I walked out of his office I glanced back and saw him just staring at the keyboard, and then he uttered the words "Which one is the RTFM key?"
I learned a lot that day and have been far more diligent with the recruitment process ever since.
I had one just like that working with me. Allegedly had a better degree than me (never proven) and had more suck for the managers than a Dyson. Also an anti-social squirt to the point of not even meeting with the rest of the team in the coffee bar which was just down the corridor from the office.
We had a bookshelf with all the relevant manuals for the software we used which sat within easy reach of both our desks. This was also the days before software had it's own help function so the manuals were often referred to.
One day as I pottered off for an afternoon coffee I heard a "what does Error [insert random number of choice]" mean?
Don't know. RTFM.
What?
It's in the manual.
Which manual?
The one on the shelf.
Came back to find that he had complained about my unhelpful attitude, to which I replied, the manual is on the shelf, it has the name of the program on the spine in big letters and all the error codes are listed in chapter 4. I'm not doing his job for him.
Oh, that’s more common than you’d like from colleagues. Hasn’t stopped in 27 years.
The disruption, the statements made afterwards but not to you, it’s fun.
In a yearly corporate review one of my colleague wrote “X never provides assistance when queries are raised, or redirects me to other resources,” was the paraphrased verbal statement “He’s stupid enough to ask me a question he should already know the answer to, has access to both the vendor knowledgebase and Google but fails to check either. and yet disrupts me - 3,000 miles away, and least a 5hr time zone distance away - whilst I’m doing my work just in case I already know his answer.”
My written response to my appraisal was “I’m very unhelpful, and intolerant of people who demand my attention because they can’t be bothered to do even the most basic of troubleshooting whilst deciding it can wait 17hrs before I’m online and they can harass me for answers.”
My manager just said “Ok”, and signed it off to go into the system.
P.S. I could write 6 sentences about what I do all year, and I’d still get the same grading if I’d written 400 sentences. In fact, I’ve been told I once wrote too much about the international trips, 3rd line specialist work, project work, home-base technical support work, etc., that I did and could not be compared to my colleagues who stayed in their home business location, did not travel, and did no development work on tools to make their life’s easier (e.g., home grown AV reporting web page, securely accessible, from anywhere in the Corporate network before McAfee produced their web-based ePO toolset so even in my travels I could give guidance to my colleagues during Slammer, etc.)
This all puts me in mind of a non-computer acronym that got attached to the then-San Diego Wild Animal Park's1 monorail ride. When opened, the zoo polled the staff of the zoo for an "African-sounding" name. A perturbed staffer returned the slip with a somewhat vulgar acronym which the dolts in management did not recognize and for years it was known as the Wgasa Bush Line.2
It is now known by the more banal but decidedly more culturally appropriate Africa Tram.3
I've never been a fan of the attraction but that's probably because my partner always seems to want to go on the hottest day of the year.
_______________
1 Now known as the "San Diego Zoo Safari Park."
Nope, especially those with a lot of knowledge know that there is sooooo much more knowledge out there. Even in their specialized field. BTW: This is the actual neutral scientific definition of the David Dunning / Justin Kruger effect. The "Popular Science" definition is what most people hear first though, which is a more visible "social result".
During my early days in the oil and gas exploration sector (in the early 1980's), there was a rumour flying around suppliers that some of the large project engineering bodies had a set of weight scales in their goods-in areas: inspection involved weighing the paperwork - and rejection if the documentation wasn't heavier than the product.
At a previous job we did some work with a company that built single engine airplanes (the kind doctors or athletes buy if they want to fly themselves around for fun). One of their quality and compliance people noted that they were pretty sure the FAA wouldn't sign off of a plane until the volume of paperwork equalled the volume of the plane.
When the company I was working for was delivering a bespoke system, I was asked to write some interim system management notes for running the system, to be delivered with the first one, to act as a stop gap while the official documentation was written (yes, the project was running late, but not because of anything involving me!)
I had later had an occasion to visit one of the sites where they were being used, and on having my name recognised, was told that my notes were being copied around and used in preference to the official documentation!
At uni, we had two "manual racks" which were a 6-foot-or-more-wide metal structures sat on tables. Each one held the multiple manuals documenting our two major mainframe systems' operating systems, applications, and user-facing peripherals.
I loved the rack and Control Data's documentation, because I could always quickly find what I was looking for by speed-scanning the manuals till I got to the relevant section. I'd check the table of contents, find the entry for what I was looking for, grasp the entire manual with my right hand, fan the pages across my right thumb, stick my left index finger in when I got "close", quasi-read the individual pages till I found the right spot, then really-read the relevant passages.
Later, the staff got microfiche readers and manuals on fiche, but they kept the manual racks and hard-copy manuals for non-staffers, because they didn't trust us with the microfiche readers.
This was fine with me. You cannot speed-scan effectively with a fiche reader.
I believe "micro film" is the term for the long strips of film, about 16mm wide IIRC.
MicroFiche, on the other hand were the rectangular single sheets of film that contained multiple pages per "leaf". Fiche, supposedly transmogrified from a French word meaning "file".
From memory (too many) decades past, when I worked as an FE on "microfilm/microfiche" machines that emulated IBM 1403 line printers.
That leads to another story, about how I brought a multi million dollar cosmetics outfit's mainframe to a crashing halt. On payroll processing day. But, let's not dwell on that.
+
When I was an apprentice at BAe Hatfield in the mid 1980s it was stated that because every part of a plane had to be inspected and documented at every stage of production, each of the BAe 146 airliners that rolled off the production line was accompanied by more than its own weight of paperwork.
There were sections in both Production Administration and Customer Support that pretty much did nothing but collate the paperwwork and scan it onto microfiche for future reference should an aicraft drop out of the sky for some reason.
I recall being at a conference in the 1980's, where one of the speakers was from Rolls Royce. He was pleading for their customers in oil & gas to trust them regarding documentation. He illustrated the situation by saying that an RB211 delivered for offshore power generation had to be accompanied by several pallets of documentation; an RB211 delivered to an aircraft manufacturer just required a single maintenance manual (most of which comprised inspection checklists). Where, he asked the audience, was the logic. Someone from that audience stood up and said that the oil & gas sector needed the paperwork for quality assurance as it was important that power generators didn't break down. That was followed by an embarrassed silence amongst the mainly oil & gas focused audience - most of whom would have been frequent flyers...
"When we bought a MicroVAX 1 in 1984, the pallet containing the manuals was larger (and heavier) than the one containing the machine itself :-)"
Back when El Reg had a semi-regular though short lived thread of articles on packaging SNAFUs, I recall a photo of a printer manual being delivered in a large box on a pallet. Just the manual. Or was it a single A4 sheet? I forget which now, but it seems the shipping dept. confused some documentation related to the printer as being the printer itself and the people working in shipping just did as they were told.
Ah, the original article is HP shatters excessive packaging world record and a splendiferous follow-up article HP excessive packaging world record put to the test by the late and much lamented Lester Haines.
Dragged out of bed on a saturday to visit an electricity prepayment machine that was feeling unwell.
Hot footed at across South Wales to the west coast to be greeted by a working machine.
The normal fix was to re-authenticate the device if the users forgot the power on PIN saving any miscreants vending free leccy.
It turned out that a remote fix had become available utilising the land line number and a remote dial in to confirm correct ownership.
When I called the ticket in and had a bit of a moan about 100 miles of wasted trip I was asked if I'd read the manual. The manual that was updated via the postie who arrived after I'd arrived on site.
Meh.
I'm not sure if here is where I wanted to put this, but it's from Douglas Adams's novel, "So Long, and Thanks for All the Fish". When electronic book, The Hitchhiker's Guide to the Galaxy has just been updated over sub-ether, or some nonsense like that.
"Ford flipped the switch which he saw was marked 'Mode Execute Ready' instead of the now old-fashioned 'Access Standby' that had so long ago replaced the appallingly stone-aged 'Off.'"
If he was alive today, he could sue Microsoft for stealing the idea of changing the names of things that were fine before - except that appearing here implies that reality invented it first. Offhand, the example I'm thinking of is "Intellisense" as the new name for "spelling", but there are better ones.
At a recent job interview I talked about "sitting down with the books" when talking about something with which I was passingly familiar but keen to learn about. It only doing the post-interview mental review as I drove home afterwards that I started to wonder when I last sat down with an physical book in my hands, probably from O'Reilly.
Dead tree books probably a fair while ago as electronic versions on a decent ePaper device are as good if not better.
I often refer to the ebook version rather than going to another room to get the paper book. Although there are quite a few older texts that haven't been digitised that admittedly are mostly of a historical or theoretical interest.
The idea of reading a book on an unfamiliar subject in its entirety to gain a reasonable foundation noticeably started to disappear around the late 1990s. Something to do with attention span I suspect. Has deteriorated to the point that even reading Google vomited garbage is too great a cognitive load.
The pervasive "AI summary" is Douglas Adams' electric monk in the 21st century that not only does the believing for you but also the thinking and learning.
Of course for any non trivial subject you have to reread the text just to resolve the inevitable forward references.
> Dead tree books probably a fair while ago as electronic versions on a decent ePaper device are as good if not better.
No. They are not. Physical books are far easier to search and scan, if you don't really know what you're looking for.
And if you do know what you're looking for, enough to search in an e-document, then you don't need to search for it.
Whenever we upgraded a software product, I would take home the Migration Guide to read. (My colleagues thought I was weird.) Sadly, the idea of such a guide seems to be unknown to most modern software developers, but for large products like OSs, compilers, revision control systems, etc. it is beneficial to find out about changes before the new version replaces the old.
Yep; one shelf for the hardware, one for the OS, one for the network software, part of one for each of the other components (database, printing, compilers, security, storage management, third-party products, ...); some of the people I worked with complained that there was /too much/ documentation!
I'm often frustrated, especially when reading man files, by missing information (e.g. permissible parameter values) and lack of examples. Without those I find myself guessing about what a lot of the options do or how they work.
For example, many applications provide options for setting fonts, but depending on the tools used to write them, there are at least three possible syntaxes for a font specification, but without at least one example, using the option is a matter of trial-and-error. At least one of the packages I like to use is very difficult to work with on a high-resolution display because its default font is specified as 'xwindows_font "fixed"' (but no size is documented) and none of the possible ways of specifying an alternate that I've tried works. There are quite a few applications I've run into whose font specifications are equally vague.
As for examples, the man file for update-alternatives does provide three, but each of them can be understood by reading the option description; for the one really complicated option, --install, there is no example at all. :-(
And of course searching for help at sites like stackoverflow produces plenty of /almost/ on-topic posts...
I saw someone working on his beautifully-restored Jaguar E-type along side of the road. He had the hard-copy manual sitting, paper-weighted open to the relevant section, on the roof of the car.
Electronic manuals do not work in all places where you might need the information contained therein.
The major issue with RTFM is you need somebody competant to WTFM. When writing documentation myself I always try to put myself in the mind of the concussed bumblebee trying to read it, and very early on there is an *ENTIRE* list of *ALL* functionality (cf the PHP discussion), from which you are able to know that there is detailed information later on.
The variety of documentation for a given system seems to have distilled to one document equally unusable in either what material is omitted or what is included.
The distinction between the "guide" and "manual" appears to have been lost.
Admittedly some systems are so incoherent as to be impossible to document effectively.
Once AI is assigned to produce the documentation we might as well abandon all hope.
Occasionally you encounter well written, clear documentation which doesn't waste your time or patience that is a pleasure to read. I hope that any author of such works receives their reward in the next life as it's unlikely they would be recognised in this. AFAIK there isn't a literary award for technical documentation. Should be.
Last autumn I was told to document everything for a yet-to-be-employed developer to take over my stuff. I started a new job elsewhere just in time for mass-redundancies and the first company were dumb nice and had me back. I was both annoyed with how much I'd forgotten and pleased with how well I documented.
Icon cos I think I deserve a pint
I have concluded that I have been totally spoiled by the high quality of the documentation that IBM provides for their proprietary software, which, in e.g. a Command Reference manual, in addition to the basic description, syntax diagram and argument and options lists, explain the allowed values for said arguments and options and when they can and can't be included and in what order they can be entered, as well as examples. error and severity codes. For each product there was typically a separate Planning and Installation Guide, Command Reference, Messages and Codes manual, and sometimes more.
No longer having access to the IBM systems I cut my teeth on, I am reduced to fumbling around on my Linux machines with their third-class man files.
Unfortunately, IBM is now less interested in making documentation available.
I work with AIX, and the current documentation is not a shadow of what it used to be. Too often, when looking at a new version of software which has existed for a while, the current documents are just a re-hash of the old ones, with extra features mentioned but not explained. So you have a stupid situation where the older, well understood parts are well documented, and the new additions barely get a mention, let alone a decent explanation.
In the past I would have put this down to IBM trying to sell their education services, but as these are now almost completely non-existent, that can no longer be the case.
And to cap it all, one of the primary resources that used to be usable to make up the gaps, a site called developerworks, was shutdown some years back, making years of knowledge unavailable (yes, I know it directs you to another site, but that sire does not seem to contain the old developerworks content, or if it does, hides it very well).
You've reminded me of a comment I posted on a Linux sysadmin forum while trying to set up a file server
"I'm more than willing and capable of RTFM if someone could point out which FM to R"
IMO open-source documentation in general can be a minefield of obsolete, superceded and badly written information. Yes, I try to give back by improving it where possible, but the world moves far quicker than I can type ...
Indeed, one of the important requisites for writing good documentation is to have in the review loop someone(s) who have no knowledge of the product's internals, acronyms, etc.; otherwise the documentation will likely be quite opaque to the product's user community.
It's also helpful for the documentation to be written before or during code generation; if it's left until afterward it might not get written at all. :-)
Wikis are a good way of representing general knowledge, but unless designed and curated carefully, are a very poor substitute for properly structured product documentation.
Too often, when considering internal documentation for a company, a wiki has been set up for people to edit and contribute to, with no proper style or structure instructions.
What then happens is a free-for-all, where different people contributing different bits to the overall documentation have their own ideas about how it should be broken down into it's constituent sections, and where proper cross-references between articles is never done, because people do not have time or feel it is appropriate to go into other's articles to put pointers to what they've just added. This leads to a morass of copious, disjoint documentation that is almost impossible to read or process, even using a wiki's search features. The information's probably in there, but finding it in context is difficult.
Where a wiki does seem to work better is as a presentation of more formal documents that have been converted to a wiki to ease making it available.
A long time ago, back in the days when documentation was measured in metres of shelf space, I had a customer who upgraded his (minicomputer) system and requested the manual set to be pre-shipped. It transpired that he took them on holiday with him to read. I think he's the only person in the entire universe who read the Batch and Spooling manual. Not only that, but he submitted a documentation error report on it on his return from vacation.
A previous employer in the 1970s was a middling large IBM shop. It was common for there to be a special rack/binder thing that held all the significant software manuals in a convenient place for the "operators". This would hold about two feet of books. Then the hardware reference books, oversized blue binders, kept on site by the IBM service engineers, had their own roll-around bookshelf.
I still have occasion to visit a machine room that was re-purposed from being used for mainframes, to now being full of IBM Power systems.
Part of the 'fit' of the room is a rolling cart with wires cages across from front to back and a solid top.
I find it amusing to have to explain to curious younger colleagues that this is a documentation cart which used to be used to hold mainframe maintenance documentation and system specific log information used by the IBM engineers. Now, it's just used as a cart to put things on, even though it's not that useful for the task (it's really too tall, but it's often the only thing we have available!)
In a similar vein, I find it amusing that you often see the orange Louisville step ladders that used to be shipped with IBM mainframe, SP2, BlueGene and some of the larger Power systems lying around machine rooms, still useful long after the systems they were shipped with have been scrapped.
Not just any old ladders, service-qualified ladders. One for each side of the machine. Specifically P/N 46G5947 and P/N 00E4866. And for gawd/ess's sake, don't forget your hardhats! That would be P/N 5442867, and you'll need 2 each because it takes two to install or replace anything that needs a ladder ... that would be anything over 29½ U.
Is your Torque Tool (P/N 6422789) properly calibrated for the job?
In the shop where I cut my teeth on command-line UNIX systems, the acronym was commonly decoded as:
Read The <F-word of choice*> Man Page
Being inexperienced, and this being an ancient time where the UNIX "man" command was (a) an option to be chosen during installation, and (b) a source of information that was ACTUALLY USEFUL, I considered this a good thing. It didn't take very long for me to lose count of the times that I found salvation there, in the jungles of the "online" manual.
Now, fast-forward to the 2010s and my final instance of "paid employment" in the field. Some of my co-workers were taking a "course" on UNIX/Linux command-line utilities, and had reached the "lesson" covering the "man" command. One of them asked me a question about some command-line option to said "man" command, and I didn't recall the specifics for said option. Therefore, my response was "go ask it", which totally confused the questioner. I had to point out to him that it was perfectly permissible to type "man man" at the command prompt to be presented with all sorts of "useful" info about the "man" command.
As I was in a generous and kind mood that day, I waited until I had returned to my own "desk" to chuckle over the expression on his face.
* <F-word of choice> is OBVIOUSLY varying according to environment and/or audience. Some possible values ( in alphabetical order ) have been known to be: Fabulous, Fantastic, Fine, .... ;^P
Running alongside "man" was the "learn" command that used to be in AT&T versions of UNIX, which would give a guided tutorial on the system for several parts of UNIX and the command set.
Unfortunately, when Linux was young, at the foot of any man page (if there was one) there may well have be a line which reads "For full documentation, type info <command>", which when you do, you get exactly the same information in "GNU info" format, with nothing more informative.
Nowadays, it seems to point to online documentation more frequently than a local texinfo source.
I used to use the permuted index of the UNIX man pages all the time, along with the "man -k" keyword search. All useful in their time, but now delegated to obscurity and irrelevance.
Having said that, and rather strangely, I have been seeing more tools being shipped with either pre-formatted man pages, or sometimes even nroff sources again. Not sure why this is but it's an interesting trend.
Was a very underrated skill in the pre-internet days. These days most people's first instinct is Google, and second instinct is posting on Reddit or stackoverflow. Back when you didn't have those options you either needed to be good at figuring things out from reading the manual, or go to one of those who were. Otherwise I guess you were calling the vendor like the customers in this story.
I was an independent consultant for nearly 20 years getting a pretty sweet hourly rate (allowing me to retire at 51) so I ALWAYS had time to respond to stuff like that in as much detail as they would like! Heck if someone was willing to pay my rate for a gig where I did nothing but that I'd probably come out of retirement since that'd be an easy WFH without any set hours!
I remember those.
A rare sight these days. Yeah Google exists, but I use it to find manuals. If there is no manual, as is often the case these days, then and only then do I resort to user posts.
But, as Carl Sagan once said, "We've arranged a civilization in which most crucial elements profoundly depend on science and technology. We have also arranged things so that almost no one understands science and technology. This is a prescription for disaster.”
IBM often authored documents in STML - Simple Text Markup Language (OK then printed them out) - who knew where that would go....
(also GTML - General Text Markup Language - I think that had more options).
p.s. after I have installed some household appliance and explained the basics to my wife, then if she asks some obscure question about it, I often reply "RTFM" - I taught that one to her :-) and it is now common in our extended family!
The problem is, as always, that the answers might be in that shelf of binders but the customer has got other things to do that learn it all. Users just expect water when they turn on the tap, they're usually disinterested in the intricacies of the water supply system.
Writing documentation isn't just a matter of running the code through doxygen, ideally user documentation is done (overseen, edited) by skilled writers who aren't that technical and didn't actually work on the project.
Before I got to the 4th paragraph, I knew this was about DEC's Great Orange Wall. Dozens of large orange 3-ring binders containing everything you ever wanted to know, and some stuff you didn't, about whatever it was you had purchased.
A surprising number of them contained "See Fig 1" at the end of the volume which is where the reader would find a full page image of the power cord plug. (I might have this last bit a little scrambled - it was 40-50 years ago.)
I've always felt that RTFM responses to questions are not only unhelpful but made in complete defiance of the way the RTFMers were themselves taught.
Nobody lobs a textbook at a university student and says "read this cover to cover".
If I want to RTFM someone, I cite the specific place in TFM I am suggesting they R.
That way they go away quickly and learn what they are asking about.
Win-win.
Depends.
Sometimes people would rather interrupt other people than read themselves, even when they're ostensibly the expert (but don't like reading)
someone who has a habit of asking you to read the manual for them (and should know better) can be told to do their own job
Other times, techy people aren't great at the people skills, but somehow end up getting pestered by users
And sometimes, people are just rude and/or elitist
Wrong, back in the days of printed manuals, reading them cover to cover is exactly how we learnt things.
It's also why we can say RTFM because we know it is in there, but we aren't saying to read it all, there are things called contents and indexes to get you to where you need to be.
Back when I was supporting a lot of HP instrument controllers, every unit our company purchased shipped with a complete set of O'Reilly's manuals. Most of which were just move directly to the dumpster.
I managed to save a set. And they still occupy a place of honor in my home library (about three linear feet of shelf space). It turns out that most of each manual consisted of one or two introductory chapters on their subject matter. Followed by printed versions of the applicable "man" pages. So, not that time consuming to read.
About 1990, I was editor and tech support in the documentation department at a DEC VAR (value added reseller -- the company sold our company's software on DEC hardware to our customers).
To test a new system our documentation department, I ordered a DEC ULTRIX (their branded version of UNIX) system and a couple of dumb X-Windows terminals to run the DEC branded version of the software that was about to become popular as FrameMaker. We were comparing it to Interleaf Publisher.
This was my first experience with UNIX, and my only experience setting up a DEC system. We saved a few bucks by not paying for installation. The on-site DEC guy was pissed. But it was no harder than setting up any 1990s era equipment.
Anyway, as related elsewhere, the vast majority of the shipping boxes were the documentation. (Plus one identical carton containing only a screwdriver, because we didn't pay for installation!) 99.99% of the prettily printed and 3-hole-drilled pages were... the UNIX man pages.
I was especially annoyed when I was trying to track down a small issue and realized that I had to go from man page to man page to learn what happened in the init software, but I basically was writing my own document to itemize the system's particular boot sequence. I called support to confirm my research, which the (post "shiboleet") geek tech confirmed. So I proceeded to gently berate her for the lack of decent overview documents describing the ULTRIX setup. I might also have pointed out a major error in the graphics card installation sheet. She acknowledged the situation, told me my research was correct, and confirmed her team was on call for whatever issue I ran into.
But I never needed to call again. I ended up not recommending the ULTRIX setup, nor the crippled DEC publishing software, nor Interleaf Publisher, because it was impressive, but overkill for us. I recommended bog-standard (DEC manufactured) MS Windows PCs running FrameMaker. Much more cost effective and straightforward to support.
