2

In the context of a technical manual, I need to write instructions guiding users through several standard manipulations. When providing examples of these manipulations, I have written a short sentence containing "before" and "after" examples which appear in (potentially multi-line) vertical blocks of their own. As a result, I am unsure as to whether the middle of the sentence should be capitalized. Additionally, a suggestion was made on ELU SE that removal of colons leading the code blocks may be preferable. I have presented an example of this below as well.


With capitalization

Hence, the following code:

camera.start_recording('foo.h264', quantization=25)

Should be replaced with:

camera.start_recording('foo.h264', quality=25)

Without capitalization

Hence, the following code:

camera.start_recording('foo.h264', quantization=25)

should be replaced with:

camera.start_recording('foo.h264', quality=25)

Without capitalization or colons

Hence, the following code

camera.start_recording('foo.h264', quantization=25)

should be replaced with

camera.start_recording('foo.h264', quality=25)

My instinct suggests the second or third examples are preferable, but I'd be interested to learn of any style rules addressing this. For that matter, if there is a better way of structuring such examples which avoids these issues altogether, I would be most interested!

Should I capitalise "or" between examples? was the most relevant question I could find to this one (and indeed was the corner of SE where I first posed this query, before being made aware of Writers), and I tend to agree with its reasoning that the lowercase version is preferable. Unfortunately the best suggestion in its answer (to use a bullet list of examples) doesn't really lend itself to potentially large blocks of code.

6

In my opinion, any answer looks messy. One "sentence" with capitals halfway through bugs me; so does a line starting without a capital.

Personally, I would restructure the entire thing to avoid the issue entirely:

Example 1

Currently, line 57 of camera.py looks like this:

camera.start_recording('foo.h264', quantization=25)

In this line, the parameter quantization needs to be replaced with quality, giving us this:

camera.start_recording('foo.h264', quality=25)

Example 2

Look at Figure 1 below. Our code currently contains line (1); we need to replace it with line (2).

(1) camera.start_recording('foo.h264', quantization=25)

(2) camera.start_recording('foo.h264', quality=25)

Figure 1 - Two versions of line 57 of the code in camera.py

(Obviously I don't know your code file name, line numbers, or programming language. Substitute where necessary. "camera.py" can be replaced with Example 1 if you're taking that route.)

  • 1
    I like your second solution, but I'm in a bit of a quandry here. Were I writing for experienced devs I would happily use a patch format for this on the basis that any experienced dev would be happy to interpret it. However, this specific project, picamera, has an educational thrust and needs to be understandable by all experience levels. For that reason I suspect your first solution is preferable in this case. Specifically, this question was to do with the deprecation chapter – Dave Jones Mar 18 '15 at 1:06
  • 1
    I've just finished re-writing the deprecation chapter according to example 1, and I'm absolutely sold on it (even more than I was before). The fact it affords the opportunity to explicitly state (or reiterate) the action to be taken immediately before the "new" snippet is particularly nice, and the new version of the text feels much better to me. Thank you! – Dave Jones Mar 18 '15 at 12:00
  • @DaveJones Glad I could help. – Watercleave Mar 18 '15 at 14:11
  • I feel example 1 is better than example 2, because example 1 actually points out the specific difference. In this case it's tolerably clear even without that, but other cases might not be as clear cut. Highlighting the difference aids in interpretation of the text. – a CVn Sep 14 '17 at 20:13
1

I like the third version, without colons, because the visual break and the code formatting makes it clear that this is a new "clause," or thought, and the piece of code is not a grammatically correct full sentence. Since you are continuing one sentence over several breaks, I wouldn't use capitals.

I think Watercleave has another good solution if you can't settle on any combination of punctuation and capitalization.

  • 1
    Thanks for the answer - of the options I presented in the question I agree that the colon-less version also looks preferable to my eyes (and I agree with the reasoning that it was one broken-up sentence). Still, Watercleave's suggested re-structuring won out in the end; despite the extra work involved, the new text feels clearer and avoids the issue altogether. – Dave Jones Mar 18 '15 at 12:10
1

I approach code in text in the same way I approach dialogue: the code is a quotation from another "speaker", so I set it off from the surrounding text. Since it is not spoken language, I do not use the conventions for spoken language (same font, quotation marks, etc.), so as to cause no confusion, but the conventions for displaying code (monospaced font, line numbering, blockquote, etc.), but I integrate it syntactically in the same way, for example by using colons and continuing sentences with lowercase letters.

Therefore, in my opinion, your second example is best.

Example:

When five year old Maude said: "I am not interested in horse riding," what she actually meant was: "I am afraid of horses".

Similarly:

Hence, the following code: camera.start_recording('foo.h264', quantization=25), should be replaced with: camera.start_recording('foo.h264', quality=25).

Of course you must not put commas inside the code quote, as English rules require for dialogue ('riding,"'). When you put your code snippets on separate lines for better readability, the syntax, capitalization and punctuation remain the same.

A good practice is to print the whole script in an appendix, and thoughout the text use the same line numbers as in that appended script. You can then refer to code by line numbers:

In line 21, quantization must be replaced by quality:

21 camera.start_recording('foo.h264', quality=25)

  • 1
    This is an intriguing suggestion, and I'd love to give it a try at some point in the future. Unfortunately I can't at this time as the particular system that I'm writing the docs with (ReadTheDocs) lacks the ability to format in this manner (and frankly I'm unlikely to abandon it because the sheer convenience of its other features vastly outweigh its shortcomings). Still, I look forward to trying it out in future projects. Thanks! – Dave Jones Mar 18 '15 at 12:04
1

Do the simplest thing that works, which in this case is example 3. The rules of sentence structure don't really cover these kinds of things. That is a defect of the rules of sentence structure, not of the examples themselves.

Remember that the first rule is clarity. Grammar rules and style guides exist to codify the practices that usually produce the clearest and least ambiguous result. They are a good guide most of the time. But these rules are the servants of clarity, not its master, and in some cases clarity will demand something that these rules cannot account for.

Doing something more convoluted or complex in order to stay onside with a grammar rule or a style guide is putting the horse before the cart. As George Orwell said, "Break any of these rules sooner than say anything outright barbarous."

0

I have to document code use on occasion and I prefer a clear cut structure, so I would simply say:

The following code camera.start...

should be replaced with: camera.start_...

Programmers won't care about your grammar choices, they will only need to know what code to use. Just my two cents worth. Thanks

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.