{"id":2949,"date":"2009-11-23T09:06:00","date_gmt":"2009-11-23T09:06:00","guid":{"rendered":"https:\/\/test.simple-talk.com\/uncategorized\/what-if-bad-documentation-gets-there-first\/"},"modified":"2016-07-28T10:49:49","modified_gmt":"2016-07-28T10:49:49","slug":"what-if-bad-documentation-gets-there-first","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/blogs\/what-if-bad-documentation-gets-there-first\/","title":{"rendered":"What if bad documentation gets there first?"},"content":{"rendered":"

I read an interesting blog snippet<\/a> a while ago about information visualizations and their capacity to set change our view of the world. It asks whether we as information designers have a moral responsibility to our users that governs how we model their worlds (“First, do no mimetic harm.”). <\/p>\n

I feel like that about documentation sometimes: it’s not ok to keep kicking the rescue dog, regardless of how used to that he is.<\/p>\n

I’ve spent a bit of time with the documentation for a very large, very serious and business-y product lately. We’ll be doing something in a similar sphere. Some of it is loathsome. There’s poor design, poor writing, typos, and inconsistencies. It’s hard to navigate, and harder to get quickly into and out of if you have a specific workflow problem. And its users lap it up. They laud it; it’s what they claim to want. <\/p>\n

This makes me sad. But is it better to pander to their lowered expectations, or take the moral high ground and give them help that, well, helps?<\/p>\n

At a glance, it’s a no-brainer. Existing documentation in the sphere is “bad” (my definition, admittedly), and a user-centred approach is “good”, so we’ll do it the good way, right?. But the bad documentation has set the expectations. So by making something that looks like the existing offering of obtuse reference tomes, we’d look less threatening, less unusual, maybe more serious and credible. Could it, pathological though this may seem, even be more usable?<\/p>\n

In that blog post, Andrew Walkingshaw argues that information representations can shape experiences more powerfully than we might first realise. We know that a bad (or worse, misleading) documentation experience has a detrimental effect on a user’s view of a product or brand, but what happens if the documentation is useful and true, but fails to match a pre-existing mental model?<\/p>\n

Do existing users really love the “bad” documentation, or are they just habituated to it, experiencing a contorted kind of of Stockholm Syndrome for manuals?<\/p>\n

It reminds me of a tweet a while ago, something like “If you knew it would increase revenue, would you change your website’s font to Comic Sans?” There’s a whole separate blog in that, but briefly, I’d want to know exactly what users were responding to, and why. <\/p>\n

I guess I feel just as queasy about high-handedly deciding I know what’s best as I do about continuing to kick the puppy. It comes back to content curation again – if it isn’t working as designed, we’ll have to revisit and likely change it. Still, it’s hard to know which way to go first. <\/p>\n","protected":false},"excerpt":{"rendered":"

I read an interesting blog snippet a while ago about information visualizations and their capacity to set change our view of the world. It asks whether we as information designers have a moral responsibility to our users that governs how we model their worlds (“First, do no mimetic harm.”). I feel like that about documentation……<\/p>\n","protected":false},"author":170602,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[2],"tags":[],"coauthors":[],"class_list":["post-2949","post","type-post","status-publish","format-standard","hentry","category-blogs"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/2949","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/170602"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=2949"}],"version-history":[{"count":1,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/2949\/revisions"}],"predecessor-version":[{"id":24917,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/2949\/revisions\/24917"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=2949"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=2949"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=2949"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=2949"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}