A Deliberate Omission

Webcomic Storyline: 

Help Desk, by Christopher B. Wright

Comic Transcript: 

CUSTOMER: Hello, I'd like to find some documentation on your UberSecuR(TM) Suite of Identity Authorization tools for Ubersoft Webserver.

ALEX: Oh, we don't provide any documentation for that.

CUSTOMER: You don't provide any documentation at all?

ALEX: We prefer to force our customers to pay overpriced consulting fees whenever they run into a problem.

CUSTOMER: That's very unethical.

ALEX: It's one of our best revenue models.


Comments are active for 30 days after publication. If you wish to comment after 30 days please use the Forums.

This reminds me of a C

This reminds me of a C compiler with a conspicuously absent help file.

Re: Which one was that

That would be Microsoft's Visual C++ v. 6.0. (I use both Linux and Windows.) For the most part, I get by with the help file that came with Borland's compiler (for Windows 3.1.) I am not about to access msdn with the same machine that has my source code, thank you very much.


MSDN is locally installable, you know. No need to have an Internet connection on your source code machine, if you're that paranoid.


What this reminds me of most is the revenue model which is actually recommended for open-source: give the software away for free and make your money off of support.

True, but...

1) Open source software is invariably documented somewhere, somehow, by someone.

2) When M$ calls open source a virus because it does this kind of thing (and other things), and then you find out certain M$ products are not documented SPECIFICALLY for this purpose, that is a much more vicious thing by comparison.

"Documented somewhere, somehow"

I like that phrase. It implies a sort of Indiana Jones vibe: if you want the documentation to the package, you must brave the legendary tomb of Stallmanhotep III.

In reality, of course, open-source documentation tends to only be documentation if you really stretch a point, and call something which somebody knows but has never written down "documentation". And the "somehow" in "somewhere, somehow" is almost inevitably "for an outdated version with an incompatible interface."

I'm not arguing that Microsoft is in the right, mind you -- I'm just saying that their track record on providing documentation is better than open source, and that this complaint, coming from open-source advocates, is a major piece of "do as I say, not as I do".

To be fair...

... in this instance I'm not poking at Microsoft. This comic was inspired by RSA.

Writer, former musician, occasional cartoonist, and noted authority on his own opinions.

inspired by RSA

What?! You mean Alex is moonlighting? (That would explain the missing netbook.)

As far as open source goes, I don't believe it to be either a great miracle that will lead us into a golden age or a plague on humanity. The problems with Windows do not stem from it being closed source. They stem from Microsoft spending more time thinking up useless features to market than spent making code work right.

I stand corrected.

I've gotten used to not being able to find the news stories your strips are based on (My Google-fu is weak) so I just assumed. Doesn't alter the argument, though.

Sherlock Holmes and the Case of the Missing Netbook

As someone that uses her netbook as her primary home computer, I would guess that the netbook is on the desktop, but it hidden by the very large external monitor. It would appear that Alex somehow acquired a monitor, keyboard and mouse and is trying to adapt to the new netbook.

Free Software Documentation does exist

Most people don't even look at the home page of projects
here are a few one link from the top:

free software
see also, installed help, man pages, info pages (regardless of the dfsg view of them)


if you don't know and won't look you can pay for support :)

and something over there too, if you like brown or purple:


Free Software Docs Do indeed Exist

Been using Fedora for years. More easy in recent years to find docs, but always could...even for advanced programming subjects like creating shared-memory blocks and queues in memory.
I have seen a lot of folks that look once, then get impatient. Or folks that ask ridiculous programming questions, like "How do I write a program to control a robot?", which trumpets to the world they haven't a foggy clue what they are doing. I try to patiently tell them to go find a "Hello World" program, and go from there.

MSVC 5 was the best

Sure, it was not very compliant with C and C++ standards, but it had the best self-contained documentation of any version. I still have my original CDs, but do not have it installed right now.

Ah, here come the Linux Youth.

"I have never needed more documentation than was available on one particular project, and therefore no project has a problem with insufficient documentation." I had heard that "works for me" was a typical way for Linux users to dismiss problems, but had never seen it in action before. So, uh, thanks.

As long as we're citing examples, let's take Mailman, the GNU mailing list processor. It's been on major revision 2.x for basically a decade (2.0 betas were in 2000), and on version 2.1.x for... to be honest, I'm not sure (and as my Google-fu is, as I said, weak, I'm not going to keep doing the research) but definitely for years. Nevertheless, the "Documentation" section of the Mailman website until this year still only had reasonably complete documentation for version 1.x, and even now does not have complete documentation for version 2.1. Need to know what fields are allowed when editing list web pages? You won't find the answer on the website -- and, in fact, you won't find a definitely complete answer anywhere unless you know enough Python to understand the source code and download it yourself, which is like being unable to go to a bakery until after you have made your own bread.

Er... Vic...

The PDF manual for Mailman claims to be at version 2.1.

But on the whole, if we ignore the sarcasm, you're mostly right: Free/Open Source software will always lag behind other operating systems in terms of documentation. Most of it is driven by volunteerism, and you get more volunteer programmers/developers than volunteer tech writers. That said, your description was a lot more accurate in 2000 -- ten years later the situation has improved a lot. It's still hit or miss depending on the application, but some applications are extremely well documented. Others are well documented in specific areas, and lacking in others... and some are still a wasteland of faqs, howtos, and forum posts.

I've been a technical writer for seventeen years, and during that time I've seen the quality of documentation for proprietary projects decline drastically, again over the last decade. It used to be when I bought I a software application I also got a manual: these days I'm lucky if I get a 20-page pamphlet with some woefully inadequate online help. It's all about the money -- technical writers are generally the first people to get axed when a company downsizes because managers think "well we'll just get the developers to write the documentation" and the developers are generally too busy trying to get the application to work to put a lot of time and effort into that.

Linux documentation has improved over the last decade, proprietary system documentation has declined, and as a result the gap is a lot narrower than it was. The people who have proprietary products who made the decision to blow off their product documentation have no one to blame but themselves for that.

Writer, former musician, occasional cartoonist, and noted authority on his own opinions.


"I have never needed more documentation than was available on one particular project, and therefore no project has a problem with insufficient documentation."

I can't seem to find the comment you are quoting. Although, with the theme of the thread, a "works for me" dismissal is actually appropriate. I'll use an analogy. If someone tells me that a computer won't turn on when he presses the power button and I hit the power button and it turns on, there really is nothing more than I can say than that it works for me. (Mind you, on my first computer, I had to call for help finding the power button. In an interesting design decision, the power button was flush with and the same color as the outer casing -- plus I had been looking for a very obvious switch.)

Re: Er... Vic...

The PDF manual you are referring to is the manual for list subscribers; it doesn't cover how to install Mailman, configure it, set up a list, administer it, edit the web pages, or really do much of anything. It has required basically no changes since version 1, because Mailman is so feature-poor compared with proprietary software like LISTSERV* that there isn't much to write about. It's like claiming that Apache's documentation must be up to date because you found the installation instructions for the latest version of Firefox.

*LISTSERV is an excellent example of how not to do proprietary software pricing. It's a dramatically better software package than Mailman, both for subscribers and for list administrators, but the license prices are based on the number of lists and subscribers, and are so ambitious that they reach well into the thousands of dollars very quickly. So if you want to run a single mailing list open to the public (and thus with an open-ended number of subscribers) you can either use Mailman, or spend something like $1000/year for LISTSERV, or pay for L-Soft's likewise-ambitiously-priced hosting service.

In addition, I'd say you're overlooking something: the bar for proprietary software for end users has become so high on ease of use that a manual is superfluous in many cases, and the online documentation on the more complicated stuff has generally become so good that a printed manual would merely be a waste of paper.

All the proprietary applications I use are laid out in such a way that I can discover the features I need by exploring the GUI, and I don't have to worry about doing this because all the proprietary programs support sensible levels of Undo, and have intelligently-distributed commit points where I can back out of major operations. The last time I needed to look something up in the documentation for a proprietary application was when I installed a major upgrade which dramatically rearranged the interface of the program in question, and I somehow completely missed an option in the Preferences window even though I looked straight at it. (That is, the last time I had to look something up, it turned out I would have known the answer if I had been paying attention.) Even then, the online help system gave me the answer, so I didn't even need to look in an actual manual, although one was provided as a PDF.

In contrast, the free programs I have used almost always make me wish for a manual which isn't there, at least when they aren't making me wish I could wring the necks of the people who write them. OpenOffice, to take an egregious example of bad design, does an excellent job of hiding even relatively simple features in massively overloaded multifunction dialog boxes. And thanks to the state of the documentation, you can never really be sure if a failure to do what you wanted is because you missed something, or because a feature is genuinely missing or broken, unless you are lucky enough to find a note which tells you they just can't do whatever it is. Apache's documentation, likewise, is designed neither to be read in a single sitting nor to be a handy reference; if you have to construct a complicated .htaccess file, you'll find it easier to search for blog and forum posts from other people who have already done whatever you want to do and copy their techniques. And don't get me started on Xorg, GRUB, apt, Perl, PHP, Emacs... in fact, as a general rule, if the only documentation you get without access to the Internet is in the form of man pages, the program is poorly documented.

I'm not even sure if it would be possible to make a living providing support for most open-source products. Given the choice between paying ~$30 for a book about OpenOffice in order to learn how to use it to its full potential, or just buying some proprietary software for ~$100, I would buy the proprietary software. The GUI will probably be higher quality, the included online documentation will probably be at least as good as the ~$30 book, and chances are that the program will integrate better with my OS, have more features than OpenOffice, or both. (Heck, there's no such book, and I'm already using proprietary software for my document creation needs, so I'm doubly unlikely to run out and buy a copy of Learn OpenOffice in 6 Easy Lessons and 12 Hard Lessons.)

Re: Vicar:

No, a "works for me" dismissal is not actually appropriate. (It very seldom is, when you come down to it.) Not only are some of those examples of documentation not really very good -- only good enough for the person who cited them, who apparently never actually ran into any problems -- but the list is not a representative sample of the open source world as a whole.

A better analogy is this: we go to a series of five restaurants and order filet mignon with a salad and bread. One actually gives it to us, one gives us a hamburger with lettuce and tomato on a bun, and the rest ignore us completely. You say, "well, I really only needed protein, vegetables, and carbohydrates twice today, so in actual fact I had filet mignon, a salad, and bread at all those places." The two aren't the same, and you didn't even get the substitute everywhere.

A manual is never

A manual is never superfluous, and "the gui is so good it doesn't need documentation" is just a big a cop-out as "this is all the documentation I need, so it's all the documentation you'll get."

Writer, former musician, occasional cartoonist, and noted authority on his own opinions.


I find it rather interesting that you say "works for me" is not appropriate while giving essentially the same dismissal as regards proprietary software. I think that your analogy doesn't fit because I am not seeing specific features (in this thread) for which people are looking for solutions and not finding documentation. Since all we have is a vague reference to sufficient / insufficient documentation, rather than specific undocumented issues, someone who finds the documentation sufficient can only say something on the order of "works for me," and would be justified in doing so. If a particular undocumented feature had been brought up, then addressing the feature would be expected.

All righty, then...

First off: I didn't say that having a manual was a waste. But having printed documentation is a waste. Even in complex programs, large portions of a manual will be useless to the overwhelming majority of people. (Think of those lists of developer credits which always use at least a page, for example!) Much better to send it out as a PDF (or a self-contained set of web pages or some other such format). The people who need printouts can get them (and can probably omit printing some of the stuff they don't need), and those who only want to look something up quickly (the majority) don't have to print anything. Sorry if I was unclear.

Can you give me an example of publicly-released proprietary software with enough enthusiasm or financial backing behind it to reach version 2.0, which has serious flaws in its documentation? (No fair using custom programs developed with training sessions in mind.) I can do the equivalent repeatedly for open-source software.

As for examples of documented proprietary software, which it seems I am to provide to avoid "works for me". I'm at a Mac right now. Looking through the installed proprietary software, here's what I find (wow, an opportunity to use the definition list tags! I've always been pleased in a mild way that they are allowed here):

Mac OS X
No print manual included beyond a truly brief installation guide, but go to the "Help" menu and choose "Mac Help", and you are presented with what amounts to an instruction manual, distinct from the troubleshooting content, fully searchable, filled with hyperlinked cross-references, and technically printable (although that's stretching a point -- each page would need to be printed separately)
Comes with extensive hyperlinked online help, plus a PDF of a written manual is included with the program (and you can order a hard copy from Bare Bones if you can't or don't want to print it yourself but need a hard copy)
Multiple sources of online help, including step-by-step tutorials and the usual hyperlinked, searchable help files. I think there was also a small printed manual included with the installation disk, but I don't have the box on me right now to check.
OmniGraffle Professional
Multiple searchable hyperlinked help files, the primary one being basically an online version of a print manual.
The least-documented program I found: it only (!) has a 37-page PDF manual and a menu item which opens the website. On the other hand, since the manual doesn't try to explain the mathematics or dynamics of Bezier curves in any detail -- only how to use the controls to modify them -- I am hard-pressed to think of anything the program does which is not covered in the manual. Vector graphics may be tricky to explain to the layman, but the controls needed to manipulate them are not.

(I'm sorry the list is so short; I only recently got around to installing 10.6 on this machine, and I have only been putting programs on as I have needed them.)

(Although I don't use Microsoft Office and have no plans to do so, the "assistant" technology which this strip mocks in the form of Binky is really just a high-tech piece of documentation. And it is irritating, and therefore mock-worthy, not because it was incapable of helping -- which would make it bad documentation -- but because it was too aggressive. It has been removed from more recent versions, but the content is still there. Microsoft Office has excellent online documentation.)

Now, to take the other side, let's see if I can remember some of the critical things not mentioned in documentation of open-source software which I have encountered in the relatively recent past (say 2 years) (oh, hey, I get to use the unordered list tag, too -- this is a red-letter day!):

  • Total absence of any indication on how to turn off tap-clicking on a touchpad, which Xorg configures to be on by default and which is not configurable in the GUI of any Linux distro I've tried on a laptop. Man page for Xorg is useless for this purpose; no documentation was found at the time via Xorg's website; finally found a forum post which described the right settings, which are not at all obvious. Apparently, there's a GUI tool for this -- but you have to know to install it before you can use it, and its existence isn't documented.
  • Trying to deconstruct someone else's .htaccess file to figure out why it was doing something weird, discovered that Apache's documentation is basically unusable for that purpose because the relevant material is organized in such a way as to make this task unbelievably awkward. (Fell back on multiple Google searches, one for each term, and thus did not use the actual documentation but forum posts, tutorials, and blog entries.)
  • Trying to construct a new .htaccess file to do something else, discovered that Apache's listing also cannot be conveniently used to do this because the relevant material is organized in such a way as to make this unbelievably awkward. (Between this and the previous point, I really have to wonder what purpose, exactly, the Apache documentation writers think people will be using the documentation of the .htaccess options for. Apparently, you're supposed to read the documentation all the way through, and then Just Know Everything from that point onward. But that's not important now.)
  • Various troubles trying to format a 40-page document I wrote in OpenOffice (voluntarily!); the documentation (at least at that time -- there have been a few minor releases since then, and the documentation might have been improved) abounded in restatements of button labels, as in "[Button Text]: This turns on the [repeat Button Text] option." This is a waste of the time of both the documentation writer and the readers, since any user capable of reading the documentation will be able to read the button text themselves, and will presumably be reading the documentation to find out what the option actually does. At least the vastly incomplete Mailman documentation has the integrity to occasionally admit things like "this section is not completed". The OpenOffice documentation also was useless on the subject of limitations of certain formatting options, such as formatting on the table of contents.
  • Bug in Xubuntu's system updater which would cause apt to fail on the first run and leave the database locked so no further updates via GUI interfaces to apt would work; not mentioned on the website, despite being apparently widespread. Finally discovered a bug report via Google, dated before that release of Xubuntu, in which the devs basically announced their intention to leave the bug alone in the upcoming release -- and not even include any sort of notice on the website -- because the problem could be fixed by opening a terminal and issuing an unlock command to apt. (Things like this remind me why I don't use Linux if I can possibly avoid it. The bug could happen to anyone -- although it would almost certainly have been caught in QA and corrected before release if it happened in a proprietary OS -- but the attitude that it's okay because you can fix it from the command line sums up too much of what is wrong with Linux on the desktop.)
  • Trying to configure GRUB to allow my test laptop to boot Windows XP, Xubuntu, Ubuntu, and (for fun) Haiku, discovered that all the visible then-current documentation from Canonical referred to GRUB 1, which is very different from GRUB 2, which is what Ubuntu in fact installed. (Not entirely Canonical's fault; Google's results had much the same problem, and the GRUB 2 wiki, where all the official documentation is, hides all the real information for users beneath the testing and debugging information. So this is a documentation issue for multiple products! Yay!)
  • Trying to install Haiku, discovered by trial and error that the partition will only boot from GRUB -- which the website mentions as a good choice of boot loader -- if you formatted the partition to use a Windows file system before conversion to BeFS, which is great for experimenting Windows users, but not so good if you formatted your Haiku partition using the Ubuntu installer, where Ext4 is (was? I seem to recall hearing that they finally acknowledged the disappearing large files bugs in Ext4 and switched back to Ext3, but that might have been some other distro) the default. This is not mentioned in the Haiku documentation, as far as I can see, although it is critical in order to use the alphas.

(I'm purposely not including a more serious issue I had with XFCE in the list, because doing so would be unfair. It was caused by a bug involving a rare graphics card and only reported to the XFCE authors after the release of that version; documentation can only realistically be expected to list known bugs likely to involve a large proportion of users, like the one above about apt, which seems to have effected quite a large proportion of users of that version of that distro.)

If you would like, I can go on, but I think I have demonstrated that several real-world pieces of open-source documentation have (or have had) genuine flaws which made it difficult to use the projects in question. Now, if you want to show me the error of my ways: give me serious flaws in documentation of real (and hopefully common) proprietary software: genuinely complex issues which can't be found, known issues which are left alone, lists of options which are incomplete or spread across multiple sections for no reason, or sections which are published though officially incomplete. If proprietary software documentation is genuinely as bad as you have variously claimed, this ought to be fairly common. I was able to come up with a string of examples, despite only dabbling with open source.

And read all the way through...

... to 1868!

Writer, former musician, occasional cartoonist, and noted authority on his own opinions.

"Can you give me an example

"Can you give me an example of publicly-released proprietary software with enough enthusiasm or financial backing behind it to reach version 2.0, which has serious flaws in its documentation?"

I already have. Visual C++ 6.0. It has no manual either. Having the documentation available only separately from the software constitutes a serious flaw. I seem to recall someone ridiculing the idea of documentation being available "somewhere, somehow."

I'm not going to convince you that open source is the way to go. Nor am I even interested in doing so. All the software packages have their own pros and cons. People have to decide for themselves which trade-offs they will make. I don't go out and get a lot of software. I purchased an assembler and compiler so that I wouldn't have to. That's my trade-off. Now, it stands to reason that commercial software would have more documentation than open-source software. It should; you're paying for it. But from what I am hearing, that is becoming less and less the case. I can and do work around the absence of a manual or help file for the compiler. But, really, I think there should have been a help file.

I do note this. From what I have read of your posts, you seem to hold software from large companies to a lower standard than you do open-source.

Pissing contest

In an effort to divert this to a more fun discussion I will start with Fedora pisses further than ubuntu.


P.s. The one and only who could stop this is you chris. Write a damn comic so we can stop being like dogs chasing our tails.