{"id":4142,"date":"2024-06-03T01:42:00","date_gmt":"2024-06-03T06:42:00","guid":{"rendered":"https:\/\/dwaynephillips.net\/workingup\/?p=4142"},"modified":"2024-05-11T06:48:50","modified_gmt":"2024-05-11T11:48:50","slug":"this-isnt-a-mystery-novel","status":"publish","type":"post","link":"https:\/\/dwaynephillips.net\/workingup\/2024\/06\/this-isnt-a-mystery-novel\/","title":{"rendered":"This Isn\u2019t a Mystery Novel"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">by Dwayne Phillips<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Writing about technology on the job breaks just about every rule taught in creative writing classes. That is because you are writing to inform, not entertain.<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Sometimes I encourage others at work who are writing about technical topics. Their job is to inform. I encourage them not to entertain.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Use the same words over and over again all the time.<\/li>\n\n\n\n<li>Tell the punch line at the start.<\/li>\n\n\n\n<li>Be logical, not emotional.<\/li>\n\n\n\n<li>And so on.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">All these encouragements are counter to what is taught in creative writing classes. That is because technical documents are not mystery novels. We don&#8217;t drop little clues and hints here and there hidden in cleverly woven webs. We state things right up front in plain language.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">We try to make it difficult for the reader to misunderstand. We try to avoid the great &#8220;Aha!&#8221; moment at the last word in the book.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Boring. Boring? Yes. That is the point. Clarity and brevity. Obvious. Not entertaining.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>by Dwayne Phillips Writing about technology on the job breaks just about every rule taught in creative writing classes. That is because you are writing to inform, not entertain. Sometimes I encourage others at work who are writing about technical topics. Their job is to inform. I encourage them not to entertain. All these encouragements [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[114,113,32,3,5],"tags":[226,225,154,126,128],"class_list":["post-4142","post","type-post","status-publish","format-standard","hentry","category-brevity","category-clarity","category-communication","category-technology","category-writing","tag-brevity","tag-clarity","tag-communication","tag-technology","tag-writing"],"_links":{"self":[{"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/posts\/4142","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/comments?post=4142"}],"version-history":[{"count":1,"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/posts\/4142\/revisions"}],"predecessor-version":[{"id":4143,"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/posts\/4142\/revisions\/4143"}],"wp:attachment":[{"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/media?parent=4142"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/categories?post=4142"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dwaynephillips.net\/workingup\/wp-json\/wp\/v2\/tags?post=4142"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}