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? 🙂
I would say, relative time references are a nuisance, but what really drives me nuts is articles / (product) docs where there is no absolute reference in time whatsoever.
You get a link to an interesting article and there is zero inline or header information WHEN that article has been written or published.
Then you have to go around fishing in metadata or using the Wayback Machine to find out when that particular piece of info first appeared.
Happens WAY too often. 🙂
This reminds me of your previous post, 'On the dangers of giving a product feature the name “new”', where various commenters gave examples of things called "New" that, well, aren't new any more.
My favourite of the list is from Daniel Rose - a part of Germany with the "alte Neubaugebiet" and "neue Neubaugebiet" - or "old new development area" and "new new development area". But there's also things like New College (one of the oldest colleges in Oxford, where 75% of Oxford colleges are newer than New College), and the Altneu Schul (old-new synagogue), which got renamed because it was...
Yeah, never name something “new”… it’s the most reliable way possible of guaranteeing it will linger long after it should have been killed off.
Something else I’ve noticed in long-term documentation is that if the current description has evolved significantly the documentation may mostly describe the changes, e.g. “you should use Foo instead of Bar to Baz.” This is probably useful when the changes were recently implemented, but if you arrive after the evolutionary stage has completed the documentation can be hard to understand because you as the reader lack the context of the older version.
I love wrestling with a particularly old and convoluted piece of code that’s still called “NewSomething”
It probably references a function called “FooExEx3” as well, which should actually now be “Foo4” since some refactoring that happened a decade ago.
Funny timing on this post, because I was just thinking about the same subject at work today, updating some older documentation. Ended up using phrases like “As of writing (Jan 2025), …” all over the place… a little clumsy, bit effective enough.
I have a rule that I bring out when doing code reviews: Flag every use of the words “now” or “new” (the latter especially in names of files, classes, functions, etc. when someone is trying to contrast the way the stuff they’re adding with the stuff that’s already there).
Trivia: New College, founded 1379, at the University of Oxford is the most extreme example that I know of demonstrating how using “new” can get you into trouble 🙂