In documents like feature proposals or pull requests, be careful with words referring to points in time, because it’s not always clear what the implied point of reference is.
For example, there might be a discussion in the pull request that goes like this:
Person 1: “If the file is missing, what happens?”
Person 2: “Currently, it crashes if the file is missing.”
There is ambiguity here in what “currently” is referring to.
- “currently in the repo”: As things stand now (before my changes), it crashes if the file is missing.
- “currently in the pull request”: If you build with the changes in the pull request, it crashes if the file is missing. (It didn’t crash before I made the changes.)
A similar ambiguity exists in feature proposal documents.
There will be a method for reversing the polarity of the neutron flow.
What is the reference point for the future tense?
- This feature proposal includes a method for reversing the polarity of the neutron flow: “Now” is the state of the system today, without the feature.
- A future feature proposal will include a method reversing the polarity of the neutron flow: “Now” is the state of the system after the initial feature is complete (but before the follow-up feature is implemented).
The word “currently” gains another possible meaning in feature proposal documents.
- “currently in the implementation”: If you try out the feature in our fun fork, it crashes. (We plan to fix this, but that’s how it behaves in the fun fork today.)
I’m just asking for clarity when using adverbs of time. Different readers may have a different assumption as to what the reference point is.
Bonus chatter: There’s another issue with temporal terms, and that’s using terms like “recently” in long-term documentation. The temporal term may have made sense when the document was written, but after months or years pass, “recently” isn’t so recent.
For example, on an internal wiki, there was a remark:
There has been a recent change to X that changes how Y’s are managed. If you have a Y, you need to perform a Z update on your existing Y’s.
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.¹ So it wasn’t really all that recent. In particular, I created my Y only a few days ago, so I didn’t need to do a Z update. My Y was created already-updated.
¹ Is there some wiki blame command that lets you see who last changed a sentence in a MediaWiki wiki?
Reminds me of recorded messages when I call a service saying "please pay attention to the menu numbers as they have recently changed". Got that same message maybe 12 months apart from one of my banks - those menu numbers were the same both times. 99% of people don't call enough to know the numbers ahead of time, so the message doesn't help. And someone who calls enough to know the menu choices is going to very quickly learn the numbers are changed and adapt anyway.
My Health fund website, just yesterday, has the message on its login page saying "new...
Re a MediaWiki “blame” tool: The Wikimedia Foundation has developed multiple tools with functionality like that, but they all appear to be rather complicated, and I’m not sure how amenable they are to self-hosting for your own private wiki. Search [mediawiki blame] for specifics.
The various “blame” utilities are nice, but it’s also not that hard to manually perform a binary search on the page history.
Yeah, a long long time ago, I created my own blame tool, working on a page history export from MediaWiki (use [[Special:Export]]): https://github.com/mormegil-cz/mwtools/tree/master/PageBlame
> Is there some wiki blame command that lets you see who last changed a sentence in a MediaWiki wiki?
WikiBlame is your friend
Soooooo what point in time does The Old New Thing refer to? 🙂