{"id":110797,"date":"2025-01-22T07:00:00","date_gmt":"2025-01-22T15:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=110797"},"modified":"2025-01-22T16:42:18","modified_gmt":"2025-01-23T00:42:18","slug":"20250122-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20250122-00\/?p=110797","title":{"rendered":"Be mindful of temporal terms in documents: What is the reference point in time?"},"content":{"rendered":"<p>In documents like feature proposals or pull requests, be careful with words referring to points in time, because it&#8217;s not always clear what the implied point of reference is.<\/p>\n<p>For example, there might be a discussion in the pull request that goes like this:<\/p>\n<blockquote class=\"q\">\n<p>Person 1: &#8220;If the file is missing, what happens?&#8221;<\/p>\n<p>Person 2: &#8220;Currently, it crashes if the file is missing.&#8221;<\/p>\n<\/blockquote>\n<p>There is ambiguity here in what &#8220;currently&#8221; is referring to.<\/p>\n<ul>\n<li>&#8220;currently in the repo&#8221;: As things stand now (before my changes), it crashes if the file is missing.<\/li>\n<li>&#8220;currently in the pull request&#8221;: If you build with the changes in the pull request, it crashes if the file is missing. (It didn&#8217;t crash before I made the changes.)<\/li>\n<\/ul>\n<p>A similar ambiguity exists in feature proposal documents.<\/p>\n<blockquote class=\"q\"><p>There will be a method for reversing the polarity of the neutron flow.<\/p><\/blockquote>\n<p>What is the reference point for the future tense?<\/p>\n<ul>\n<li>This feature proposal includes a method for reversing the polarity of the neutron flow: &#8220;Now&#8221; is the state of the system today, without the feature.<\/li>\n<li>A future feature proposal will include a method reversing the polarity of the neutron flow: &#8220;Now&#8221; is the state of the system after the initial feature is complete (but before the follow-up feature is implemented).<\/li>\n<\/ul>\n<p>The word &#8220;currently&#8221; gains another possible meaning in feature proposal documents.<\/p>\n<ul>\n<li>&#8220;currently in the implementation&#8221;: If you try out the feature in our <a href=\"https:\/\/devblogs.microsoft.com\/oldnewthing\/20240625-00\/?p=109931\">fun fork<\/a>, it crashes. (We plan to fix this, but that&#8217;s how it behaves in the fun fork today.)<\/li>\n<\/ul>\n<p>I&#8217;m just asking for clarity when using adverbs of time. Different readers may have a different assumption as to what the reference point is.<\/p>\n<p><b>Bonus chatter<\/b>: There&#8217;s another issue with temporal terms, and that&#8217;s using terms like &#8220;recently&#8221; in long-term documentation. The temporal term may have made sense when the document was written, but after months or years pass, &#8220;recently&#8221; isn&#8217;t so recent.<\/p>\n<p>For example, on an internal wiki, there was a remark:<\/p>\n<blockquote class=\"q\"><p>There has been a recent change to X that changes how Y&#8217;s are managed. If you have a Y, you need to perform a Z update on your existing Y&#8217;s.<\/p><\/blockquote>\n<p>I had a Y, and I was worried about having to Z. But then I went to the wiki history, and that sentence was added several months ago.\u00b9 So it wasn&#8217;t really all that recent. In particular, I created my Y only a few days ago, so I didn&#8217;t need to do a Z update. My Y was created already-updated.<\/p>\n<p>\u00b9 Is there some <tt>wiki blame<\/tt> command that lets you see who last changed a sentence in a MediaWiki wiki?<\/p>\n","protected":false},"excerpt":{"rendered":"<p>What is your implied point in time for the reference?<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[26],"class_list":["post-110797","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-other"],"acf":[],"blog_post_summary":"<p>What is your implied point in time for the reference?<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/110797","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=110797"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/110797\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=110797"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=110797"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=110797"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}