Ask HN: Do you prefer 'how to' articles to include command line output?

https://news.ycombinator.com/item?id=5307608

by ianox • 13 years ago

2 2 13 years ago

news.ycombinator.com

When reading 'how to' articles that require commands to be run at the terminal, do you prefer to see that actual output of the command included in the article, or just the command itself (knowing that you'll see the output when you execute the command)?

dmckeon• 13 years ago

Yes, if the output is not so verbose as to obscure the next command(s). If the article is hypertext, then output could be hidden (in an alternate article version with output, behind a link for each command line to text output or a screenshot, in alt text, etc.)

For the experienced user, command output may be predictable (and for traditional Unix commands, may be of length 0), but for the user unfamiliar with the commands being used, example output can serve as a confirmation that the right command was used, the desired result ensued, etc.

For less-experienced readers, be sure to provide specific commands, rather than falling victim to a recent unfortunate trend to give only a vague text description of the needed commands:

vague: "then install Frobnicate and use it on the frammis."

clear:

    # yum install frobber-tool
	<example output>

    # frob /dev/frammis
	<example output>

Test: if a reasonable user would ask how, where, or what, the instructions could be more explicit.

pdenya• 13 years ago

I want the output of the command available in the article. I've seen it in show/hide boxes before, but yes, if it's relevant at all, show it.

Ask HN: Do you prefer 'how to' articles to include command line output?

Related Stories