Probably the most common problem that I see in technical documentation is a failure to say upfront what the thing is that you\u2019re documenting.<\/p>\r\n
I feel that in most cases, one of the first pages of the documentation set should have a sentence early on in the page that says something like \u201c[Product name] is \u2026\u201d and then a brief statement about what the product is.<\/p>\r\n
(A statement like \u201c[Product name] does \u2026\u201d can also work, and in some contexts is even better; but in many contexts that framing can continue to leave it unclear what the product is<\/em>. For example, the statement \u201cMyProduct makes your life immeasurably better\u201d doesn\u2019t tell the reader what MyProduct is.)<\/p>\r\n Without that kind of definition, someone who isn\u2019t already familiar with the product can read dozens of pages of documentation and still not be sure what the product that they\u2019re reading about really is. Is it an API? A web application? A platform? An image-processing chip? A wearable computer? A floor wax? A dessert topping? Who knows?<\/p>\r\n So do your readers a favor and tell them upfront what it is that you\u2019re documenting.<\/p>\r\n\n","protected":false},"excerpt":{"rendered":"","protected":false},"author":5,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[72,114],"tags":[],"class_list":["post-17106","post","type-post","status-publish","format-standard","hentry","category-peeves","category-tech-writing"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/posts\/17106","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/users\/5"}],"replies":[{"embeddable":true,"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/comments?post=17106"}],"version-history":[{"count":2,"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/posts\/17106\/revisions"}],"predecessor-version":[{"id":17108,"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/posts\/17106\/revisions\/17108"}],"wp:attachment":[{"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/media?parent=17106"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/categories?post=17106"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.kith.org\/jed\/wp-json\/wp\/v2\/tags?post=17106"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}