{"id":5160,"date":"2016-08-17T12:22:05","date_gmt":"2016-08-17T17:22:05","guid":{"rendered":"http:\/\/www.encoretechresources.com\/insights\/?p=5160"},"modified":"2016-08-17T12:22:05","modified_gmt":"2016-08-17T17:22:05","slug":"writing-clearly-about-documentation-can-be-done-of-course-it-can","status":"publish","type":"post","link":"http:\/\/www.encoretechresources.com\/insights\/2016\/08\/17\/writing-clearly-about-documentation-can-be-done-of-course-it-can\/","title":{"rendered":"Writing Clearly About Documentation Can Be Done \u2013 Of Course It Can"},"content":{"rendered":"

\"0153a034e4c0dc755026166b439c4461\"<\/a>“Give every person his or her due” \u2013 a prime precept, if there ever was one. Why are we noting it here? Because Neal Kaplan on the Customers and Content blog<\/a> warns about a couple of dangerous myths, a caution we second \u2013 that “programmers can’t write and writers can’t code.”<\/p>\n

That’s pigeon-holing people when we should be thinking of eagles flying high. In this new digital age, people need to be recognizing complementary skills and developing them to the best of their abilities \u2013 human abilities, which can span categories. <\/p>\n

Citing an article that got under his skin, “Why Developers Write Horrible Documentation<\/a>,” Kaplan faults its writer for thinking in terms of generalizations, a hazard to be sure.<\/p>\n

The particulars<\/em> of the matter come down to what a given technical writer accomplishes both in terms of programming and<\/em> explaining it well. It can be done. And it needs to be done more and more often. <\/p>\n

Supposedly, developers get too close to a product. Well, did Herman Melville get too close to whales in producing Moby Dick<\/em>? Of course not. <\/p>\n

Developers can create a usable product, but they can’t be trusted to write the documentation? “Here’s the thing,” Kaplan explains. “maybe no one taught the developers about product docs, about what works and what does(n’t), about what their users are looking for.”<\/p>\n

But they can learn \u2013 as Kaplan explains, he himself did. Complexity requires insight to get on better terms with understanding. Learning, rather than harpooning. <\/p>\n

Lest we be accused of mixing eagles with whales, we’d best make the clear point that what comes out of a workplace is forecast by how relational and cooperative its denizens are.<\/p>\n

Tasks clearly understood are likely to be tasks performed well. That’s a principle for technical writers and their colleagues to honor. \u2013 Doug Bedell<\/em>
\n (Photo via Pinterest)<\/em> <\/p>\n","protected":false},"excerpt":{"rendered":"

“Give every person his or her due” \u2013 a prime precept, if there ever was one. Why are we noting it here? Because Neal Kaplan on the Customers and Content blog warns about a couple of dangerous myths, a caution we second \u2013 that “programmers can’t write and writers can’t code.” That’s pigeon-holing people when […]<\/p>\n","protected":false},"author":7,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3,5],"tags":[],"class_list":["post-5160","post","type-post","status-publish","format-standard","hentry","category-technology","category-the-writing-life"],"aioseo_notices":[],"aioseo_head":"\n\t\t\n\t\n\t\n\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t