Take the 2-minute tour ×
User Experience Stack Exchange is a question and answer site for user experience researchers and experts. It's 100% free, no registration required.

In a few programming tutorials I am writing, I use quotations to indicate what the program should display if the output is short; such as:

The program should output "Hello World"

However, it irks me to have the sentence without any punctuation. Most websites that focus on essay writing state that the punctuation should go inside the quotation marks; but to me that implies that the punctuation is part of the output.

Should I write the sentence like this:

The program should output "Hello World".

Or should I use some other convention to indicate output when I type it inline with the text?

share|improve this question
    
"Hello World" should be output by the program. –  jberger Dec 21 '11 at 18:08
6  
I've learned from our friends at English Stack Exchange that the period inside the quotation is an American convention, and there's not necessary anything wrong with having the period outside as long as you're consistent. –  Patrick McElhaney Dec 21 '11 at 19:09
1  
You might also restructure the sentence with a colon and line break before the output. –  tajmo Dec 21 '11 at 21:30

3 Answers 3

up vote 3 down vote accepted

Neither. In this case, we are talking about programming, and "strings". It should be specific. If we aren't putting in a "." then we shouldn't say we are going to see one, even if it's grammatically correct.

When learning how to program, it is incredibly import to convey how sensitive the syntax is. Evey period (.) comma (,) semicolon (;) etc must be used with care. This is one of the common mistakes beginners make when learning how to write code. Forgetting to use a period in the middle of the syntax, or putting one where one doesn't belong can throw off the entire intended operation. So, to aid the experience of someone who is trying to learn such a specific skill, all of the documentation should he as clearly written as possible.

While adding the period to the end is grammatically correct according to the Yahoo Manual of Style as stated in another answer, why take the chance of introducing confusion if we are trying to drive home the point of how important periods are in a programming syntax? The simplest and most straightforward approach should be favored here, after all we are trying to help someone through a difficult and mentally exhaustive process. The easier it goes, the better.

To take that even one step further, you should remove even the quotes around "Hello World" and use italics, bolding, or color to emphasize the output.

I would also restructure the sentence so that the "Hello World" is not at the end. For example:

You should see Hello World on the screen.

This way you avoid the situation entirely.

share|improve this answer
    
However important the punctuation characters may be in a programming language, the writing in question is a tutorial, not a code example, thus the publishing rule of "ending a phrase with period" applies. As per the rest of the answer it has already been pointed out rewording the phrase as an option. –  Naoise Golden Dec 21 '11 at 19:01
3  
To your point, it's probably better not use quotes at all, but use typography to make the string stand out. (For example, the style sheet on this site specifies that code should have the styles: background-color: #F3F3F3; color: #222222; font-family: 'Droid Sans Mono',monospace;.) –  Patrick McElhaney Dec 21 '11 at 19:13
1  
@PatrickMcElhaney agreed :) –  Matt Rockwell Dec 21 '11 at 19:17

I think your question had the right answer, in a way:


The program should output:

Hello World


Further, how are you displaying output when it is long? The most readable tutorial would maintain the formatting regardless of the length of the output example, so if it's not in "pre" tags or set apart some other away, pick a method and stick to it throughout the document. If the reader knows that "all output is displayed like __", they can quickly scan through to match their actual output to your expected output.

share|improve this answer

According to the Yahoo! Manual of Style:

In general, place periods and commas inside quotation marks.

Example

  • Kevin McKidd had starring roles in “Anna Karenina,” “Rome,” and “Journeyman.”

If quotation marks are used to indicate a character or a string of characters that the user must type exactly, put any punctuation mark outside the closing quotation mark. Alternatively, reword the instruction so that the punctuation isn’t near the quotation marks, or use boldface type for the string.

Examples

  • For traffic conditions, type the city name, the street name, and the word “traffic”.
  • For traffic conditions, type the city name, the street name, and the word “traffic” in the box.
  • For traffic conditions, type the city name, the street name, and the word traffic.

So the right way would be either

The program should output "Hello World".

rewording the phrase

The string "Hello World" should be output by the program.

and making the string stand out, in boldface for example

The string Hello World should be output by the program.

EDIT: as noted in other answers, a more sophisticated approach is making the string to ouput stand out by other means than quotation marks. Changing the fontface, adding a highlight, etc.

The string Hello World should be output by the program.

share|improve this answer
1  
See also this explanation of why punctuation should go outside quotes: catb.org/jargon/html/writing-style.html –  Alex Feinman Dec 21 '11 at 19:48

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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