3

In software documentation, I recently read:

If you move a job to a different folder, you may also need to update configuration that was referring to that job.

But if you have a "configuration that was referring to that job" you need to update it (or really should). Not doing that will result in broken configuration and ultimately, broken behavior.

Is this use of "may need to" really correct? Is there a valid reason the documentation is phrased like this, instead of "…, you also need to update"?

Doesn't the current documentation through the use of "may" imply that there are situations where you're not required to update configuration because it handles the job move correctly?

  • I hope this can be answered without knowing what the documentation refers to exactly. Imagine it'd say "file" instead of "job" and it'd essentially be equivalent. It's like when Windows asks you to locate a moved or renamed file because a link on the desktop ("configuration referring to the job") is outdated. – Daniel Beck Oct 11 '13 at 22:01
  • 1
    I'd say you may be right. Notice how I'm avoiding any risk of libel. The cop-out type of hedged language (not all hedging is bad, though) was used on every page of an alternative medicine manual I once read: 'This herb may be beneficial for...' / 'Some people have claimed alleviation of pain after taking' / 'There may be a risk of side-effects such as...' – Edwin Ashworth Oct 11 '13 at 22:16
  • @EdwinAshworth Do they also use hedged language when describing what needs to be done to recover from a bad situation? I somehow cannot imagine someone saying "When you hear the fire alarm, you may need to leave the building". – Daniel Beck Oct 11 '13 at 22:27
  • I'd say that @EdwinAshworth is probably right or the manual writer was not very clear. To remove any ambiguity, I would write that section to say, "You will need to do X under these circumstances...but not under these other circumstances" so the user can see clearly when to do X and when not to do X. – Kristina Lopez Oct 11 '13 at 22:29
  • 1
    If a manual gives an unhedged 'if Y occurs, you need to do X' and an unforeseen case arises where that's wrong advice, the writers of the manual could probably be sued for millions. – Edwin Ashworth Oct 11 '13 at 22:58
5

Software documentation is usually written by someone following a normal or good path through the setup. Saying, "you may need to do this" is essentially a callout to known issues or problems that are extremely likely. But since the author is not going to exhaust all possibilities they just stick "may" into the sentence to cover their bases.

To attempt speaking directly to your example, the person writing the documentation doesn't actually know that such a configuration exists or that you in particular need to update or that it wasn't already updated and that's why you happen to be moving the job to another folder. And they don't need to worry about those things — instead they say "may" and write out the most common scenario.

More anecdotally, I personally do this all the time when writing documentation for various install procedures. I know my audience will be someone with a similar expertise to myself and all I am really trying to accomplish is sticking a relevant problem solving thought in their head in the event something goes wrong.

Also, you'd be surprised at how many things suddenly change in technology. We kind of get used to never saying "always" or "you must do X."

  • Note that in this case, it is confirmed by the developers (and as it's open source, I absolutely know the necessary API just doesn't exist) that there is no chance at all that you wouldn't need to update configuration referencing the renamed job. I wanted to keep this out of the question to not make it too technical. Does this change anything? – Daniel Beck Oct 12 '13 at 19:30
  • Not really, no. – MrHen Oct 13 '13 at 14:17
1

Use of may does not entail that there are situations where you're not required to update configuration. It does, however, implicate so. See Wikipedia entry on Implicatures. Grice's paper cited in the Wikipedia entry is posted online.

If you say "it is possible that X". It entails that there is a non-zero probability that X is true. It implicates that there is a non-zero probability that X is false.

Common use of "imply" usually means "entail", but is often used to mean "implicate".

0

A better phrasing might be

If you move a job to a different folder, you will also need to update any configuration that refers to that job.

(italics indicate edits) The use of will indicates certainty, and the use of any makes it clear that such a configuration might not exist. Refers instead of was referring to is because the the configuration refers to the job, which still exists, it's only moved.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.