The problem with adding more examples and suggestions to the documentation is that eventually people will stop reading the documentation


I am a member of a peer-to-peer discussion group on an internal tool for programmers which we'll call Program Q. Every so often, somebody will get tripped up by smart quotes or en-dashes or ellipses, and they will get an error like

C:\> q select table –s “awesome table”
Usage: q select table [-n] [-s] table
Error: Must specify exactly one table.

After it is pointed out that they are a victim of Word's auto-conversion of straight quotes to slanted quotes, there will often be a suggestion, "You should treat en-dashes as plain dashes, smart quotes as straight quotes, and fancy-ellipses as three periods."

The people who support Program Q are members of this mailing list, and they explain that unfortunately for Program Q, those characters have been munged by internal processing to the point that when they reach the command line parser, they have been transformed into characters like ô and ö, so the parser doesn't even know that it's dealing with an en-dash or smart-quote or fancy-ellipsis.

Plus, this is a programming tool. Programmers presumably prefer consistent and strict behavior rather than auto-correcting guess-what-I-really-meant behavior. One of the former members of the Program Q support team recalled,

It might be possible to detect potential unintended goofiness and raise an error, but that creates the possibility of false positives, which in turn creates its own set of support issues that are more difficult to troubleshoot and resolve. Sometimes it's better to just let a failure fail at the point of failure rather than trying to be clever.

There was a team that had a script that started up the Program Q server, and if there was a problem starting the server, it restored the databases from a backup. Automated failure recovery, what could possibly go wrong? Well, what happened is that the script decided to auto-restore from a week-old backup and thereby wiped out a week's worth of work. And it turns out that the failure in question was not caused by database corruption in the first place. Oops.

"Well, if you're not going to do auto-correction, at least you should add this explanation to the documentation."

The people who support Program Q used to take these suggestions to heart, and when somebody said, "You should mention this in the documentation," they would more than not go ahead and add it to the documentation.

But that merely created a new phenomenon:

I can't get Program Q to create a table. I tried q create -template awesome_template awesome_table, but I keep getting the error "Template 'awesome_template' does not exist in the default namespace. Check that the template exists in the specified location. See 'q help create -template' for more information." What am I doing wrong?

Um, did you check that the template exists in the specified location?

"No, I haven't. Should I?"

(Facepalm.)

After some troubleshooting, the people on the discussion group determine that the problem was that the template was created in a non-default namespace, so you had to use a full namespace qualifier to specify the template. (I'm totally making this up, I hope you realize. The actual Program Q doesn't have a template-create command. I'm just using this as a fake example for the purpose of storytelling.)

After this all gets straightened out, somebody will mention, "This is explained in the documentation for template creation. Did you read it?"

"I didn't read the documentation because it was too long."

If you follow one person's suggestion to add more discussion to the documentation, you end up creating problems for all the people who give up on the documentation because it's too long, regardless of how well-organized it is. In other words, sometimes adding documentation makes things worse. The challenge is to strike a decent balance.

Pre-emptive snarky comment: "TL;DR."

Comments (27)
  1. I do not agree. This is the same problem as with users that don't read any alert texts, and just press OK (or Yes or No) to dismiss them, so they let them continue whatever was they were doing. More often than not, the alert is related to the task they were in the middle of, but they don't realize that. Some people would tell that doubling the confirmation for a delete operation will make those users react, but it would have no effect, because they didn't read in the first place. If they don't read, you have lost before starting.

    In the same way, the programmers that don´t read the documentation for a command, an API, etc. won't do it. Reasons may be lazyness, lack of time, lack of understanding of a foreign language… Saying "it's too long" is a mere pretext. Furthermore, documentation has a structure: introduction, parameters/arguments, returned value, etc. Adding an example at the end (or at the "examples" section) won't make it harder or longer to read the general description of the command or API.

  2. sql-troubles says:

    "I didn't read the documentation because it was too long." The phrase is nothing but an excuse that can easily be used to save people from further embarrassing explanations. On the other side the person who made it might be right, though this doesn’t mean that we should stop document things as long we consider them important. Documentation should in general include everything that’s important and that can help the developer or user tackle a problem.

    I can’t agree with the statement that documentation will make things worse, as long the information presented are valid!!! Sure, it can be challenging to read it, though the information is there, somewhere and a simple search might reveal it. Nowadays indexing or labels help us to find things on the web and offline documents.

    Well-organized is too vague because each person has his own opinion of what this term means. The challenge I think is to split the documentation into manageable chunks of information that can be easily chewed, provide adequate navigation and search functionality, add multiple layers of relevance, make important things visible, supplement the content with definitions, drawings that could help people understand the architecture, additional resources, etc.

  3. SvenG says:

    TS;WTRM (Too Short; Want To Read More) :P

  4. Yuri Khan says:

    The problem should not even have arisen in the first place as described, because no one in their right mind writes documentation with code examples in Word, and any documentation tool should be smart enough to not apply any DWIM-like character replacement to <pre><code>…</code></pre> sections.

    I will even go as far as to say software shouldn’t do any smart character replacement; instead, keyboard layouts need to be extended and people to be taught about proper typographics, preferably as early as at about the same age they learn proper punctuation (and retroactively for all who are employed in creating content for others to read).

  5. Joshua says:

    because no one in their right mind writes documentation with code examples in Word

    In which case most product documentation teams are not in their right minds.

  6. Mordachai says:

    Folks who write TL;DR are fools.

    If they get foolish outcomes and consequences of their foolish behavior… hazah!

    RTFM

  7. spork says:

    > The problem should not even have arisen in the first place as described, because no one

    > in their right mind writes documentation with code examples in Word

    Really?  Many corporate devs have to use Word for feature specs, implementation plans, install guides, etc.  I solved this issue for myself by turning AutoCorrect off.

    [Email is a common place where this problem occurs. Somebody writes "The command you want is foo “bar baz”" and the email program "helpfully" smartifies the quotes. -Raymond]
  8. jader3rd says:

    I agree, Office manipulating special characters causes no end of grief. For me, the two big ones that regularly come up are the hyphen vs. double hyphen thing; and how I'll want to copy a line, but if the line is part of a list it'll prepend the bullet of the list.

  9. Danny says:

    Documentation too long? That's the only problem at Microsoft? Try buy Windows 7. The damn pages just keep on coming and I am no near to the "Buy now' button. Same on Office. Everything is too long at Microsoft. KISS!!!

  10. Mashmagar says:

    I definitely notice this happening for me. I'll read error messages, but not verbose documentation. I'm trying to solve a problem quickly, not learn the intricacies of the tool.

    My typical workflow for any *NIX tool:

    "Hmm… How do I do X?"

    Open man page.

    "My goodness, this is long. Is the option on the first page?"

    No. Return to command prompt and try the most likely one-character option.

    "Nope, option didn't work."

    Return to man page. Page through options, looking for same option I tried on the command line. Maybe it's a different case, or different number of hyphens, or is more than one character. This works ~50% of the time.

    "Can't find it. I give up"

    Look it up on StackOverflow.

  11. Jim says:

    Documentation for developer, what a concept. For my observation, they generally are brave enough for any troubles without any documentations.

  12. John says:

    I understand the argument, but the other side of the coin is that people can't read documentation that doesn't exist.  You can't help people who aren't willing to read the documentation, but some people are willing to read it.

  13. Joshua says:

    [Email is a common place where this problem occurs. Somebody writes "The command you want is foo “bar baz”" and the email program "helpfully" smartifies the quotes. -Raymond]

    Apparently I'm the only one in the Windows platform who passes so much programmer text via email body that it was expedient to hunt down the setting to turn that off.

    [Or you're the only person who uses quotation marks exclusively for code and never for quoting somebody. -Raymond]
  14. Joshua says:

    [Or you're the only person who uses quotation marks exclusively for code and never for quoting somebody. -Raymond]

    I tend to quote people in email in block quote style for completely different reasons. I've also not ever had people complain about getting straight quotes when quoting someone when I do use inline quotes. The real problem comes when I turn on HTML outbound email. For some reason, my accessibility settings bleed across in the email and it really bugs people on the other end, but that's another topic.

  15. Christian says:

    Open man page.

    "My goodness, this is long. Is the option on the first page?"

    I generally think that man pages are easy to read and seldom too long.

    What I hate is the sentence "The Gnu folks don't believe in man pages, please use the info command to browse the full help". I can't even use this strange info program, and I'm completely not interessted in browsing some hypertext like "book" full of useless boilerplate…

    With MSDN it used to be that the text was long, excellent and very nice to read like books.

    Nowadays it looks more like most of MSDN is deeply hierachical and cross referenced, but actual content is often missing. It looks like the help files have been redone from scratch sooo often, that all the jewels of conent have been destroyed and destroyed again and what remains is the most bloatet autogenerated boilerplate which makes MBAs happy because it's easier to translate than any actual real long content!

    Oh and to the original article: The argument that people wouldn't read the documentation if it's too long just doesn't make sense. Screw those people and make the documentation complete. Illiterate people maybe should go use a tablet and leave the computers alone

  16. j b says:

    When you write anything but plain prose in Word, always keep your left hand close to Ctrl-Z. When I write code examples, using Ctrl-Z to undo the automatic substitution, leaving what I REALLY typed, comes so instictively to me that it doesn't even briefly enter my concious mind.

  17. Maurits says:

    It's possible to have bad documentation just as much as it's possible to have bad code. It's not just a matter of making sure the right stuff is in (and none of the wrong stuff is in); it has to be organized sensibly too. For example, the section on "curly quotes are not suitable for command-line use" does not really belong in Program Q documentation; it should go in general Command Line documentation, or perhaps MS Word documentation, or perhaps the clipboard handler for the console process could do something clever.

  18. DysgraphicProgrammer says:

    The real solution is to go back in time and kill the person that implemented "smart" quotes by changing the character. *Display* them different, fine. But in memory, on the disk, and in the clipboard it should still be ASCII 34.    

  19. Cheong says:

    I always read the full page(s) of documentation whenever I use an API the first time, no matter how long it is.

    For people who think it's too long and didn't read the whole thing, it's their problem.

    Btw, current MSDN documentation format highlights points-of-failure and other important text. If the documentation has been written following similar guideline, it's really their own problem if they don't at least read the highlighted parts.

  20. Larry Hosken says:

    cheong00 writes:

    "I always read the full page(s) of documentation whenever I use an API the first time, no matter how long it is."

    Good to meet you. As a professional technical writer, I always wondered who you were.

  21. Smouch says:

    Really ?

    This topic is about issues with using copy and paste from documentation, and the misinterpretation of special characters ?

    What about all the examples that are actually totally wrong, don't compile, have logic errors, or are just plain poor coding style ?   I think the special character issue is the least of my worries when looking at examples in documentation.

  22. meh says:

    I never had much problems with man pages. I recall the output being paged via less and entering /search_string and using the various cursor movement commands to browse around.

    Also: > Pre-emptive **funny** comment: "TL;DR." (FTFY :)

  23. Anonymous Coward says:

    A few thoughts.

    Documentation is seldom too long, but it can be ill-structured. Sometimes it's just one big mass, whereas parts are only applicable in special situations, such as when an error occurs. This doesn't seem to be a Microsoft specific problem.

    @‘Or you're the only person who uses quotation marks exclusively for code and never for quoting somebody.’ – Raymond:

    We have AltGr-9 and AltGr-0 for that. Automatic quotes get screwed up too often, especially when you're dealing with words containing apostrophes. I call them ‘dumb quotes’, because the alternative robs the word ‘smart’ of all meaning. For that reason I think DysgraphicProgrammer's solution could never work; there's always some corner case that you cannot account for.

    For the record, I have actually written documentation in Word. For other programmers. This was because my manager specifically mandated that the documentation had to be written in Word. It didn't cause too many issues however, because I turned off the dumb quotes years ago and I just pressed Ctrl-Z on the minuses.

  24. Cheong says:

    @Larry: Actually I've written to MSDN documentation team a few times suggesting update / wording changes to .NET parts of documentation. (Mostly because they don't copy / refer to a more detailed explation of enum options in corresponding API part, and just used expanded words of the name of enum thats not clear in meaning)

    In some sense if you're technical writer, it's better if you don't heard from me. :P

  25. Lockwood says:

    I wouldn't say "TL;DR".

    I might say “TL;DR” however…

  26. Mordachai says:

    It does seem like in this day & age that Word should have a technical-paragraph style where auto-substitutions are never done, the default font is a code-friendly one, and it's indented and other similar things, much as you'd expect to get in most forums with the { } code-comment style (see stackoverflow.com for a good example).

    I know – wrong place for this… but ah well.

Comments are closed.