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

121–129 of 129 posts

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

#121

Post by yencabulator »

SoftTalker wrote: post #91
andirk wrote: post #28

Can we please use `example.com` for an example domain name instead of like `somedomain.com`? It can create accounts with emails that someone can actually intercept.

Another "can we please" is stop illustrating (or providing as defaults) insecure configuration examples. A large percentage of people following the examples will use them verbatim. Had a case recently where someone was setting up a postgres container and the example was something like: docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres You guessed it, "mysecretpassword" ended up being t…

My pet peeve is insecure configuration defaults. The Postgres container by default does not require any authentication for localhost connections, and with containers "localhost" can mean unexpected things.

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

#122

Post by bornfreddy »

chasd00 wrote: post #38

I gave what my company calls a “lunch and learn” presentation once of some interesting tools. People liked it and shared my deck around which was cool. But then my quick/dirty examples started showing up in best practice (I loathe that term) decks shared to very large teams with my name at the bottom. A security guy, who I greatly respect, raised some questions and I had to go through the whole story with him and the…

> It was pretty embarrassing.

Maybe, but you did learn a lot too. A follow-up that explains all those fixes might be even more interesting than original presentation, as far as I'm concerned.

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

#123

Post by eviks »

scubbo wrote: post #115
eviks wrote: post #85

Earlier quoted context omitted.

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!

if you want to be that technical, than start with the fact that you can easily mindlessly copy&paste, it just won't execute, which is technically a separate thing

(another prompt is just an annoyance for no benefit)

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

#124

Post by developer93 »

codetrotter wrote: post #70
chasd00 wrote: post #38

I gave what my company calls a “lunch and learn” presentation once of some interesting tools. People liked it and shared my deck around which was cool. But then my quick/dirty examples started showing up in best practice (I loathe that term) decks shared to very large teams with my name at the bottom. A security guy, who I greatly respect, raised some questions and I had to go through the whole story with him and the…

> best practice (I loathe that term) Me too :( One of my coworkers keeps talking about “best practice” all the time. And he writes the most broken garbage of anyone I’ve met in a long time. I’m often feel like quitting, because I do not enjoy working with him. But I like the company I work for. And I don’t want to spend time trying to find a new job at the moment.

I've found that vague reasons like "it's best practice", "that's the way it should be done" & "that's not scrum" are usually thrown about by people who don't actually know why they're doing that, they just learned it and now feel strongly about it but can't actually back it up.

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

#125

Post by redhale »

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.

Disagree. Think of any example that includes the configuration of a secret like an API key. Typically you see something like "" or "xxx-your-api-key-xxx" that signals to the user that they need to input a real value rather than leaving the default, usually coupled with a nearby note describing how/where to get said key.

The example here is of course slightly different, but I think a similar pattern could be applied.

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

#126

Post by stared »

Any template strings are ambiguous unless there is more than one example.

For example, let's imagine that there is an instruction saying that in a config file, there should be:

PASSWORD=[password]

Let's say our password is "admin". Then it could be that:

PASSWORD=admin

PASSWORD=[admin]

or even

PASSWORD=[password]

as it is not a place to actually store the password, but to select an authentication method.

Sure, sometimes (but not always!), it is possible to deduce how to fill the pattern.

If the field has some canonical value, go with a sane default e.g. "canary.their-company.com", with a note that any other suffix works instead of "canary". Sensible defaults save us a lot of brainpower (vide https://en.wikipedia.org/wiki/Convention_over_configuration).

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

#127

Post by burntsushi »

Karellen wrote: post #64
burntsushi wrote: post #41

Earlier quoted context omitted.

Does vim follow semver? (vim predates semver...) So how do you know you're comparing apples-to-apples? Look at the breaking changes in each ripgrep major release. I don't use major releases as a means of breaking popular workflows. I use major releases even when there are very small breaking changes with minimal impact.

> Does vim follow semver? I don't think vim follows semver, although a lot of old unix software, and also Free Software, would use major version bumps to indicate compatibility breaks. Semver was in many ways the documentation of what a lot of software was already kind-of doing. But vim was used as an example by the GP, so re-using it as an example to show what I thought was a sensible major-release schedule (instead…

Did you do what I asked and look at ripgrep's changelog?[1] The breaking changes are prominently advertised in each major release. Not all breaking changes are the same or have the same impact. Some major releases don't even have any breaking changes. (semver doesn't say to only do a major release when there's a breaking change. You can do a major release without breaking changes.)

I don't think you're correct about "old Unix software" using major version bumps to indicate compatibility breaks. Recent 3.x releases of GNU grep, for example, fucked around with the meaning of \d when using the -P flag. With no changes to the major version number. Did that break your scripts?

The thing about semver is that it tends to make breaking changes much more visible, which is kind of the point. And of course, when you compare it to projects that don't use semver and don't increment the major version for every breaking change, the projects using semver look like they're moving at a much faster pace. It might be true, but you can't conclude it by looking at version numbers when the projects aren't using the same versioning scheme.

[1]: https://github.com/BurntSushi/ripgrep/blob/master/CHANGELOG....

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

#128

Post by fsckboy »

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.

> Is there a reason websites put that $ in front of commands

back in the mid-early days of computers, I'm pretty sure the unix prompt was a $ (and as has been pointed out, a # for the root user). Thus custom of using it in documentation started because it's literally what people would see.

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

#129

Post by burntsushi »

Karellen wrote: post #64
burntsushi wrote: post #41

Earlier quoted context omitted.

Does vim follow semver? (vim predates semver...) So how do you know you're comparing apples-to-apples? Look at the breaking changes in each ripgrep major release. I don't use major releases as a means of breaking popular workflows. I use major releases even when there are very small breaking changes with minimal impact.

> Does vim follow semver? I don't think vim follows semver, although a lot of old unix software, and also Free Software, would use major version bumps to indicate compatibility breaks. Semver was in many ways the documentation of what a lot of software was already kind-of doing. But vim was used as an example by the GP, so re-using it as an example to show what I thought was a sensible major-release schedule (instead…

Another example of old timey Unix code just breaking things in minor point releases. See https://abi-laboratory.pro/index.php?view=changelog&l=glibc&... and https://github.com/intel/hyperscan/issues/359.
Post reply on HN