RTFM!

This Is a Rant

I know the title may trigger some of you, or you may not even be old enough to understand the acronym. "RTFM" means "read the f*n manual", and it was used quite a lot online, and in person, in the late 1990s and then the 2000s. Please bear with me on this, as I hope to make some points that are very valid still today.

Context, For Context's Sake

I belong to a generation of humans that had, in the computer space and outside, access to a "manual" for anything. Your new coffee machine, your car and your vacuum cleaner all came with at least one nicely printed manual. This trend was started with the quick adoption of cars and appliances after WW II, and quickly spread to anything! It then only made sense that the blooming personal computer industry of the late 1970s and early '80s would pack the box of their latest and greatest with a plethora of manuals, guides, and reference material. But... this was very "linear", i.e. in return, it was expected that the user of any machine or appliance would take at least some time to learn about the "quirks and features" (© Doug DeMuro) of their shiny new "thing".

Where Am I Going With This?

As mentioned above, the term "RTFM", though it may have been created sooner than I ever caught it, began being used quite a lot in the '90s, and specifically around computers and their software. After all, a product like the MS-DOS 3.3 retail box from 1987 included around 300-500 pages of printed manuals, depending on the specific edition you got, giving a user a good library to learn and implement, and MS-DOS 6.22 from 1994 reduced this to less than 150 pages, probably so that new users would not be overwhelmed. But it was true in 1994, as it had been in 1987, that a user would at least have access to most of the documentation for their product in printed form.

But if any user wanted to dive deeper into their new tool or cool software, they could just go to their local bookshop and find many books to purchase for any specific topic. This period is also when the famous "For Dummies" series was born. It started in 1991 with, drumroll, a book titled "DOS for Dummies", and has since expanded to cover many more topics beyond computers and software. While in university, I regularly went over to the "computing" section at bookstores, and bought a number of books I needed and liked over the years. This time, however, was about to end, and, please allow me to become sentimental about this: it is truly, deeply, missed.

As the Internet became more widely accessible to people in the early 2000s, "RTFM!" was an acronym often used to dismiss questions by new users (the "noobs") on online forums, who would ask questions that could be answered by just reading the documentation that they already had. For my purpose, at this time, most software did indeed have a solid documentation, either in printed, or, increasingly over the years, in plain TXT or PDF format, that could be accessed in dedicated directories on the floppies, CDs and DVDs that the hardware and software shipped with. This was, admittedly a strongly-worded form of telling a user that "page 193" in the manual they already had access to would have already answered their question, instead of potentially having to wait for days for the community to reply to their message. Yes, the Internet was way simpler then! (Though humans never change...)

From my personal experience, I saw that many questions I read in these forums were asked by new users out of laziness, but also because of lacking skills in English by many, at least in Europe back then, and a closer look at the provided documentation would indeed have helped them solve their issue. In one case, while working as a computer sales rep in a specialized department store, a colleague eventually snapped at a customer, literally shouting at him "when you buy a car, you don't also get a driver's license, and it's no different here!" I was not far away, serving another customer, and indeed, that person had been asking him way too many questions, that, I get, a new user would like to ask, but he, the customer, did not understand that we were there to sell products, and not provide hand-holding computing courses.

Eventually, the term "RTFM" was superseded by "Google is your friend!" in those exact same forums, making them more friendly and not too dismissive of new users.

Houston, We Have a Problem!

You see, computers and their software have become waaaay more powerful over the years, multiple magnitudes over. I'm not joking: the NASA Apollo 11 computer is outperformed by a modern iPhone, as of about 2019 or 2020, by a factor of over 100'000'000 times! While this does give me a very powerful perspective on "that thing landed humans on, and returned them from, the moon in 1969!", it also gives me another, and even more powerful perspective on the modern computing reality we live with today.

And I also realize that the reality of just over 20 years ago is simply no longer feasible, or even possible. The modern world has become much faster and more closely connected than it ever was in humanity's history. We have all purchased that gadget from Amazon or some other online platform, only to receive it with a tiny folded piece of paper, printed in Chinese and, perhaps, some poorly-translated European languages, that is supposed to inform you about its compliance with modern-day legal regulations, and not much more. Want a manual? Sure, their website's support section will be available for you, if you're lucky, to peruse all their written material, but you just need to register for a FREE account first... (🤬🤬🤬)

It is very clear that the speed with which modern products are created and shipped greatly outpaces the possibility of writing a manual that will be able to cover most, and barely all, of a modern product's features, especially in software. This is a space where I indeed hope that AI and LLMs will be able to provide new support, as products keep getting more complex (which I like), but also where finding out just why that feature behaves as it does is no longer as easy as it once was. Yes, I'm hopelessly romantic on this!

Practicality

I distinctly remember one day many years ago, when I purchased a new PC as a mechanical engineering student. Turns out, I was eligible for huge discounts on the software, and I paid for my shiny new 486DX-33 dream machine with some savings I had. (It's also pretty telling of the margins of the computer store I visited at the time that they gave me a free HP LaserJet 4L printer, and also a free HP DeskJet 500 I then sold to a fellow colleague...) Microsoft has always been, after all, quite generous with students, because they want the students of today to be already trained on their products for the workforce of tomorrow! I was indeed one of them, and included the full version of Office Professional 4.3 with my Windows 3.1 (not 3.11!) PC purchase, for just a small fee. However, due to shipping mistakes, the Office retail box only arrived weeks after I had picked up my computer, and therefore I had to go back to the store just for this.

When I arrived, the person at reception already had the package on the desk... It. Was. HUGE! While the 40+ 3.5" floppy disks to install the suite were certainly adding to the total heft, it was the number and sheer volume of the included manuals that made the box truly heavy. While I do not remember exactly how many manuals were included, and cannot find exact references online right now, I do remember there being at least two manuals for each product included in the suite: Word, Excel, PowerPoint, and Access. Each was a book of at least a couple hundred pages, so this all adds up!

Getting There

When I started this new developer journey, I sometimes found myself thinking about "how many old-style, ring-bound books would Apple need for its entire developer documentation, today?" This question came pretty much every time I ventured into the many-many-many pages of the online documentation for Apple's iOS and macOS, and Nuxt, Vue and TypeScript lately. As a fun excercise, I just asked ChatGPT "how many manuals would it take to print a well-written and beginner-friendly documentation of a modern (24.04) Ubuntu Linux distribution, in ring-bound DIN A5 size", since this is all open source and freely available. Well, see for yourself:

Manual-page Ubuntu documentation breakdown

Weight calculation for the 24-binder set

Please notice that the above does not include any packaging for the supposed 24 manuals. If this were real, and packaging all this material a "thing", it would require a great deal more packaging, think in the region of three separate cardboard boxes, probably each for eight of the above manuals. That weight is not being considered here.

You will understand that producing, printing and shipping millions of copies of just a single version of this documentation would be impractical, hugely expensive, and just plain unsustainable. With the speed of evolution computer software is going today, just the additional work needed for typos and bugfixes would be impossible to manage. Even if we forget producing actual books, generating the PDFs for each release would probably quickly drown even the most passionate startup. But documentation is necessary!

Modern Times

While I am certainly very happy about the invention of PDFs (and plain text files!) and the practicality they bring, I wanted to explore the above before making my actual point: modern documentation still needs work. As someone who is just venturing out into modern software development, I find myself having to read a great deal of docs, and I know that many experienced devs rely on docs as part of their daily jobs. There are certainly quality differences between some sources and others, but the fact is that at least some docs are as bone-dry as a desert: they show just the basic syntax, with no examples and perhaps just another reference that will be exactly as dry as the one you're coming from. I have seen this so. Many. Times!

This reality is most likely what created the modern "YouTube tutorial" ecosystem around pretty much any platform and programming language you can think of, as well as all the modern teaching platforms like Udemy et al. While I fully support that many instructors creating this material do know what they are doing, I see two big issues here. For one, creating video material that is deeper than just scratching the surface takes time and money to produce, whether you are a solo dev who wants to "spread the word", or a large company which does this professionally. Just like the books that were replaced by these video versions, your professionally-produced video covering the latest, cutting-edge release of that platform is going to get old very, extremely quickly in the "today" world. I also strongly believe that the "OG" documentation's quality has been going down in just the few years I have been actively observing... The OS/framework/platform creators no longer have the time, or sometimes even care, about making their "stuff" accessible to a wide audience, and instead just frame it for "those in the know". While there are certainly many experienced programmers out there who have no issue in quickly learning about the hot new "whatever", this attitude also leaves the rest of us mostly in the dark.

My Takeaway

I would like documentation to be more accessible to programmers of at least intermediate level. Sure, if you are just starting out, you perhaps you shouldn't even be looking at some of this stuff. Programming sometimes really needs to be very technical, I get it! But, as mentioned above, I currently find doc pages to be severely lacking, and this has almost always forced me to spend many hours searching online, and then trying out articles, blog posts and tutorials, only to realize that I either needed to learn something else, or just understand that the material I had found had been a waste of time, or even simply outdated and no longer relevant. And while I do get that "this is part of the journey", it is also deeply frustrating, and a big barrier to want to explore more.

Yes, today's pace of "ship fast" will probably make this tendency even bigger in the future. Also, the LLMs (AI models) we have available right now, while being able to help in many circumstances, are all lagging by at least 12-18 months behind the frameworks currently available to work with. Training AI models takes time, and testing them even more, so I get the "why". I will also write another post on my very first, and very enlightening, experience with ChatGPT from 2022 in another post sometime, but I would like there to be more simple documentation than what is the reality of today.

Many platforms and developer ecosystems praise their friendliness towards beginners, and some make it their tagline to say "Just look at our simple docs to get started!" However, my experience with this has been less than ideal, and I have had to spend a lot of time to understand how a particular feature or function can be made to work for ME, many times over. Yes, this is the job of a developer, and we must distill the noise away from the news to be able to create great products. But there has to be a way so that platforms provide more information, that is easier to understand, so that I, the developer, will be attracted enough to use it for my projects. Right now, the equation is lacking, though I do see hope for the future.