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?

Improve this question
5
  • 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
    Commented Oct 11, 2013 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
    Commented Oct 11, 2013 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
    Commented Oct 11, 2013 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
    Commented Oct 11, 2013 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
    Commented Oct 11, 2013 at 22:58

3 Answers 3

Reset to default
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."

Improve this answer
2
  • 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
    Commented Oct 12, 2013 at 19:30
  • Not really, no.
    – MrHen
    Commented Oct 13, 2013 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".

Improve this answer
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.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .