Homepage
Login
New Post
Profile
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.
(3)More posts by @YK4692630
3 Comments
Sorted by latest first Latest Oldest Best
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
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.
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.)
Terms of Use Privacy policy Contact About Cancellation policy © selfpublishingguru.com2024 All Rights reserved.