{"id":884,"date":"2024-04-20T12:19:30","date_gmt":"2024-04-20T20:19:30","guid":{"rendered":"https:\/\/www.timrosenblatt.com\/blog\/?p=884"},"modified":"2024-04-20T12:19:30","modified_gmt":"2024-04-20T20:19:30","slug":"documentation-for-an-unknown-future","status":"publish","type":"post","link":"http:\/\/www.timrosenblatt.com\/blog\/2024\/04\/20\/documentation-for-an-unknown-future\/","title":{"rendered":"Documentation for an unknown future"},"content":{"rendered":"\n

I found a great meme on Reddit that made me think of software documentation (probably because I think a lot about good documentation<\/a> and communication).<\/p>\n\n\n

\n
\"\"<\/a><\/figure><\/div>\n\n\n

It can be so hard to know the context that the audience will have when they read something, and I think it’s especially hard to know what can be “too obvious” to write (but might not be obvious to the reader). I think this can be especially challenging with super-strong engineers with deep domain expertise.<\/p>\n\n\n\n

I always love a good cooking metaphor, and there was a comment that mentioned how we all do this today<\/a>, maybe without realizing. When we look at a recipe for chocolate chip cookies, and it says to add an egg, we all know it means a chicken egg. We also know it doesn’t<\/em> mean a duck egg, or an ostrich egg, or salmon roe.<\/p>\n\n\n\n

This idea is core to communication, and I think it shows up a lot when writing technical documentation. It can be challenging to ensure that documentation is useful as a software feature matures. In as little as a few years, there can be subtle “aging” of the documentation, or the product, or the team, which makes the communication harder. This idea is especially highlighted by a project to communicate a message over 10,000 years like “we buried nuclear waste here, don’t dig it up”<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"

I found a great meme on Reddit that made me think of software documentation (probably because I think a lot about good documentation and communication). It can be so hard to know the context that the audience will have when they read something, and I think it’s especially hard to know what can be “too … Continue reading “Documentation for an unknown future”<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"_links":{"self":[{"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/posts\/884"}],"collection":[{"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/comments?post=884"}],"version-history":[{"count":1,"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/posts\/884\/revisions"}],"predecessor-version":[{"id":886,"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/posts\/884\/revisions\/886"}],"wp:attachment":[{"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/media?parent=884"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/categories?post=884"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.timrosenblatt.com\/blog\/wp-json\/wp\/v2\/tags?post=884"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}