{"id":4703,"date":"2013-04-10T07:00:00","date_gmt":"2013-04-10T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2013\/04\/10\/the-problem-with-adding-more-examples-and-suggestions-to-the-documentation-is-that-eventually-people-will-stop-reading-the-documentation\/"},"modified":"2013-04-10T07:00:00","modified_gmt":"2013-04-10T07:00:00","slug":"the-problem-with-adding-more-examples-and-suggestions-to-the-documentation-is-that-eventually-people-will-stop-reading-the-documentation","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20130410-00\/?p=4703","title":{"rendered":"The problem with adding more examples and suggestions to the documentation is that eventually people will stop reading the documentation"},"content":{"rendered":"

\nI am a member of a peer-to-peer discussion group on an internal\ntool for programmers which we’ll call\n\nProgram Q<\/A>.\nEvery so often, somebody will get\n\ntripped up by smart quotes or en-dashes or ellipses<\/A>,\nand they will get an error like\n<\/P>\n

\nC:\\> q select table –s “awesome table”\nUsage: q select table [-n] [-s] table\nError: Must specify exactly one table.\n<\/PRE>\n
\nAfter it is pointed out that they are a victim of\nWord’s auto-conversion of straight quotes to slanted quotes,\nthere will often be a suggestion,\n“You should treat\n\nen-dashes<\/A>\nas plain dashes,\n\nsmart quotes<\/A>\nas straight quotes,\nand\n\nfancy-ellipses<\/A>\nas three periods.”\n<\/P>\n
\nThe people who support Program Q are members of this mailing list,\nand they explain that\nunfortunately for Program Q,\nthose characters have been munged by internal processing to the point\nthat when they reach the command line parser,\nthey have been\n\ntransformed into characters like ô and ö<\/A>,\nso the parser doesn’t even know that it’s dealing with an en-dash or\nsmart-quote or fancy-ellipsis.\n<\/P>\n
\nPlus, this is a programming tool.\nProgrammers presumably prefer consistent and strict\nbehavior rather than\nauto-correcting guess-what-I-really-meant behavior.\nOne of the former members of the Program Q support team recalled,\n<\/P>\n
\n
\nIt might be possible to detect potential unintended goofiness\nand raise an error,\nbut that creates the possibility of false positives,\nwhich in turn creates its own set of support issues that are\nmore difficult to troubleshoot and resolve.\nSometimes it’s better to just let a failure fail at the point of failure\nrather than trying to be clever.\n<\/P>\n
\nThere was a team that had a script that started up the\nProgram Q server, and if there was a problem starting the server,\nit restored the databases from a backup.\nAutomated failure recovery, what could possibly go wrong?\nWell, what happened is that the script decided to auto-restore\nfrom a week-old backup and thereby wiped out a week’s worth of work.\nAnd it turns out that the failure in question was not caused\nby database corruption in the first place.\nOops.\n<\/P>\n<\/BLOCKQUOTE>\n
\n“Well, if you’re not going to do auto-correction, at least\nyou should add this explanation to the documentation.”\n<\/P>\n
\nThe people who support Program Q used to take these suggestions\nto heart,\nand when somebody said,\n“You should mention this in the documentation,”\nthey would more than not go ahead and add it to the documentation.\n<\/P>\n
\nBut that merely created a new phenomenon:\n<\/P>\n
\nI can’t get Program Q to create a table.\nI tried\nq create -template awesome_template awesome_table<\/CODE>,\nbut I keep getting the error\n“Template ‘awesome_template’ does not exist in the default namespace.\nCheck that the template exists in the specified location.\nSee ‘q help create -template’ for more information.”\nWhat am I doing wrong?\n<\/BLOCKQUOTE>\n
\nUm,\ndid you check that the template exists in the specified location?\n<\/P>\n
\n“No, I haven’t. Should I?”\n<\/P>\n
\n(Facepalm.)\n<\/P>\n
\nAfter some troubleshooting, the people on the discussion group\ndetermine that the problem was that the template was created\nin a non-default namespace,\nso you had to use a full namespace qualifier to specify the\ntemplate.\n(I’m totally making this up,\nI hope you realize.\nThe actual Program Q doesn’t have a template-create command.\nI’m just using this as a fake example for the purpose of storytelling.)\n<\/P>\n
\nAfter this all gets straightened out,\nsomebody will mention,\n“This is explained in the documentation for template creation.\nDid you read it?”\n<\/P>\n
\n“I didn’t read the documentation because\n\nit was too long<\/A>.”\n<\/P>\n
\nIf you follow one person’s suggestion to add more discussion\nto the documentation,\nyou end up creating problems for all the people who give up\non the documentation because it’s too long,\nregardless of how well-organized it is.\nIn other words, sometimes adding documentation makes things worse.\nThe challenge is to strike a decent balance.\n<\/P>\n
\nPre-emptive snarky comment<\/B>: “TL;DR.”\n<\/P><\/p>\n","protected":false},"excerpt":{"rendered":"
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 […]<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[26],"class_list":["post-4703","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-other"],"acf":[],"blog_post_summary":"
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 […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/4703","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=4703"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/4703\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=4703"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=4703"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=4703"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}