0

I have a technical document with the following sentence:

  1. Exception: To assign a_very_special_variable, use a separate line.
  2. Exception: To assign a_very_special_variable, it’s required to use a separate line.

I want to avoid the word "exception" and—for this reason—it seems I need to use the second version of the sentences and not the first.

However, I'm not really sure that the second version is really grammatically correct. I tried to find such sentences over the Internet and I have found nothing.


The following part was added after the conversation with BadZen in comments


The document is a style guide for AutoHotkey programming language. There is a following section:

Comma-separated expressions

Use them only if it really makes sense to do so.

FirstName := "John", LastName := "Doe"
Age := 20

Warning

To assign CliboardAll, use a separate line.

; OK
Clipboard := "Foo"
PseudoClipboard := ClipboardAll
Clipboard := PseudoClipboard
MsgBox,,, % Clipboard  ; => `Foo`
; Wrong
Clipboard := "Foo", PseudoClipboard := ClipboardAll, Clipboard := PseudoClipboard
MsgBox,,, % Clipboard  ; => An empty string

The first rule is just a matter of taste.

The second (that is, the one inside "Warning") is mandatory; if you break it, you get an error.

1
  • 1
    As a consumer of documentation, the most helpful way of writing this would be to explicitly say that this will generate an error and to say what type of error it is. For example: "To assign ClipboardAll, use a separate line. Assigning ClipboardAll in a comma-separated expression will generate an 'Unexpected character error /,/' at compile time." That way the reader has an idea of the cause when they get that specific error. That's not a matter of English grammar though, it's more of a rule of technical writing. Commented Sep 9, 2020 at 22:06

1 Answer 1

2

To assign a_very_special_variable, use a separate line.

is perfectly fine and preferably brief.

The second sentence is clear, but could be better worded:

To assign a_very_special_variable, the use of a separate line is required.

You could probably use either with "Exception:" in front, or without it - even though this is not strictly and properly grammatical, it is common-use and also clear what you mean.

3
  • "[the first version] is perfectly fine and preferably brief." - Don't you think that the first version looks like a recommendation and not as a strict, mandatory requirement? This is the very reason I tried to use the second.
    – user90726
    Commented Sep 9, 2020 at 17:31
  • I think it would depend on context - presumably some things come before this (since it is an "exception"), and since we don't see these, it's hard to say what the overall sense would be!
    – BadZen
    Commented Sep 9, 2020 at 17:49
  • I added a part to my question that provided the full context.
    – user90726
    Commented Sep 9, 2020 at 18:20

You must log in to answer this question.

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