Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Be careful of the examples you use. They stick

blog.thinkst.com

Post reply on HN
Print view View original

111–120 of 129 posts

Re: Be careful of the examples you use. They stick

#111

Post by Animats »

superfrank wrote: post #94

> It’s important to realise this isn’t a customer-side issue; they shouldn’t have to consider the impact of every configuration option we choose to put in front of them. They don’t have the full context and knowledge, and expecting them to be experts in the nitty gritty of Canarytoken discoverability Yes! > Going forward, we will show multiple examples of prefixes. A user looking to add a custom domain will see a var…

> Prevent users from using "someprefix" as the prefix and show them the warning again.

Yes. That's why https://example.com exists.

Re: Be careful of the examples you use. They stick

#112

Post by chrisandchris »

hiAndrewQuinn wrote: post #76
JohnMakin wrote: post #74

Reminds me of a large company I worked at, I had some documents for developers how to set up some local environment thing they had to do exactly 1 time and never again. It was just a handful of terminal commands, all starting with the traditional shell notation like: $ (some command) Over the course of a year I got periodic complaints that it "wasn't working" and I tried to find issues on my end and couldn't. One par…

Is there a reason websites put that $ in front of commands you are fully expected to mindlessly copy and paste? I've seen it happen more and more and it simply baffles me.

Yes. $ means regular user, # means root user. Usually.

Re: Be careful of the examples you use. They stick

#113

Post by superfrank »

cmovq wrote: post #99
superfrank wrote: post #94

> It’s important to realise this isn’t a customer-side issue; they shouldn’t have to consider the impact of every configuration option we choose to put in front of them. They don’t have the full context and knowledge, and expecting them to be experts in the nitty gritty of Canarytoken discoverability Yes! > Going forward, we will show multiple examples of prefixes. A user looking to add a custom domain will see a var…

> 2. Prevent users from using "someprefix" as the prefix and show them the warning again. Don't do this - examples in documentation should be valid. Having an example that doesn't work when the user tries it out will just lead to frustration.

I strongly disagree.

First, I've come across plenty of documentation that has commands that you can't just copy paste into your terminal. As long as the parts a user needs to fill in are clearly marked and explained, I don't see an issue. Especially in a case like this where there isn't a clear "right" answer and what works for one user may not make sense for another.

Second, I feel like there should be some sibling of Hyrum's Law (https://www.hyrumslaw.com/) that says that users will eventually do everything you tell them not to do.

If you don't want users to do something, then you need to protect them from themselves and explicitly prevent it. Just saying "don't do this" and expecting users to listen isn't going to work.

Re: Be careful of the examples you use. They stick

#114

Post by galbar »

JohnMakin wrote: post #79
hiAndrewQuinn wrote: post #76

Earlier quoted context omitted.

Is there a reason websites put that $ in front of commands you are fully expected to mindlessly copy and paste? I've seen it happen more and more and it simply baffles me.

I think it is to separate command line input from output - $ echo "Hello!" Hello! The $ denotes that this is a terminal command, and anything that is not preceded by $ will usually be some kind of output. That's certainly how/why I was using it.

On top of that, I find it useful to know if a command should be run as a normal user ($) and root/administrator (#).

Re: Be careful of the examples you use. They stick

#115

Post by scubbo »

eviks wrote: post #85
scubbo wrote: post #82

Earlier quoted context omitted.

> Is there a reason websites put that $ in front of commands you are fully expected to mindlessly copy and paste? As well as the answers you've already been given (distinguishes input from output, distinguishes root from non-), one answer is contained in your own question - it prevents mindless copy-pasting.

Except it doesn't, removing $ has no positive effect on your mind

I'd claim that I'm technically correct - you _cannot_ mindlessly copy-paste `$-prefixed` code into a terminal and have it execute, because the `$` will result in a syntax error - but you are, indeed, correct to say that it is possible the _then_ mindlessly delete the `$` without thinking about the rest of the content. But it's another prompt, at least!

Re: Be careful of the examples you use. They stick

#116

Post by Cyykratahk »

Karunamon wrote: post #75
Cyykratahk wrote: post #53

Earlier quoted context omitted.

Yes, here are the reserved TLDs [0]: test example invalid localhost local localdomain domain lan home host corp 0. https://www.ietf.org/archive/id/draft-chapin-rfc2606bis-00.h...

Be careful, that is a decade plus old expired draft of a proposed update to RFC 2606. The current version of the standard, including 6761 which updates it, does not reserve most of those. https://datatracker.ietf.org/doc/html/rfc2606#page-2 https://datatracker.ietf.org/doc/html/rfc6761 You are probably safe using names like .lan and .corp but they are not currently protected by standard in the way example is.

Ah, that's a good point.

Re: Be careful of the examples you use. They stick

#117

Post by tedunangst »

cmovq wrote: post #99
superfrank wrote: post #94

> It’s important to realise this isn’t a customer-side issue; they shouldn’t have to consider the impact of every configuration option we choose to put in front of them. They don’t have the full context and knowledge, and expecting them to be experts in the nitty gritty of Canarytoken discoverability Yes! > Going forward, we will show multiple examples of prefixes. A user looking to add a custom domain will see a var…

> 2. Prevent users from using "someprefix" as the prefix and show them the warning again. Don't do this - examples in documentation should be valid. Having an example that doesn't work when the user tries it out will just lead to frustration.

This gets fun when the example is something like instructions for wiping your disk to install a new OS. If you use an invalid disk name, they get errors. If you use a valid disk name, they wipe the disk on the wrong computer.

Re: Be careful of the examples you use. They stick

#118

Post by hansvm »

pdw wrote: post #25
saurik wrote: post #19

Earlier quoted context omitted.

Omg, I just read the documentation for erasedups and I'm actually shocked anyone would want that feature turned on, to the point where it never even would have occurred to me to implement it in the first place and if the feature worked like that without some way to turn it off I'd have been super angry :(. Maybe we are parsing that sentence wrong and by "shouldn't be necessary to set" the idea is "it is useful in sit…

Now I'm confused. Why would you want duplicate entries in your command history? I get that on an overloaded system in the 80s it might have taken a perceptable amount of time to filter out duplicates. But on a modern system you surely want it always enabled?

Any search of the form "what other interesting commands did I need the last time I did ?" benefits from being able to see the historical context. Or if I know the particular incantation is one I wrote several times and is very similar to some others then it's easy to search the history for the blocks of popular commands. Or whatever. It's your terminal, but given how fuzzy the interconnects in a mind can be it's hard to know what info might be useful down the road.

To your point about computing power, I think it's only now that it's reasonable to not filter the duplicates. If I want to emulate the dedup behavior it's trivial nowadays to blindly read 1M lines of history and dedup on the fly each time. Using downstream tools doing duplicate filtering/transforming work is similarly very very fast. Disk is cheap enough that I really do want to keep every command I ever write in my history. More expensive compute and disk would make me more likely to turn that feature on, not less.

Re: Be careful of the examples you use. They stick

#119

Post by hiAndrewQuinn »

jabroni_salad wrote: post #100
hiAndrewQuinn wrote: post #76

Earlier quoted context omitted.

Is there a reason websites put that $ in front of commands you are fully expected to mindlessly copy and paste? I've seen it happen more and more and it simply baffles me.

As a generalist with many operating systems in use, I like that this tells you what OS the command is for. Especially now that powershell with its many unix-like aliases is getting popular, this isn't always evident.

Yeah, alright. As the former "PowerShell guy" for an office of 200+ people when I still preferred WSL and bash, I can definitely accept this answer.

Re: Be careful of the examples you use. They stick

#120

Post by yencabulator »

cmovq wrote: post #99
superfrank wrote: post #94

> It’s important to realise this isn’t a customer-side issue; they shouldn’t have to consider the impact of every configuration option we choose to put in front of them. They don’t have the full context and knowledge, and expecting them to be experts in the nitty gritty of Canarytoken discoverability Yes! > Going forward, we will show multiple examples of prefixes. A user looking to add a custom domain will see a var…

> 2. Prevent users from using "someprefix" as the prefix and show them the warning again. Don't do this - examples in documentation should be valid. Having an example that doesn't work when the user tries it out will just lead to frustration.

There are plenty of scenarios where that is not desirable. Perhaps most famous is IP addresses: https://www.rfc-editor.org/rfc/rfc5737.html
Post reply on HN