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?