search

StyleGuides / english-for-techies

Need to convert all your dev-speak into plain English? This might help.
11 stars 2 forks source link

Revise use of "foo" and "bar" #1

Open daobrien opened 7 years ago

daobrien commented 7 years ago

We encourage (read "demand") that writers not use these terms in RH docs, so we should do the same.

Yes, it's common, understood, it's rare that ppl would take offence, but leading by example is a good idea.

notklaatu commented 7 years ago

What's the proposed alternative? Example1 and Example2, maybe?

I find that using actual commands or applications becomes very distracting. People miss the grammatical stuff and start debating whether a sentence is actually true or not.

Example:

The `rm` command is destructive, and it should never be used.

Instead of talking about whether that comma is good or bad, students debate over the value of the rm command.

daobrien commented 7 years ago

Yes, or "myApp1" and "myApp2"? Just use something that's obviously bogus, while still avoiding the foobar/fubar issue that was raised elsewhere. Is the second part of your question related, or did that come from elsewhere? I agree with your conclusion, and I think that's what happens in some of the quizzes.