Be careful of the examples you use. They stick(blog.thinkst.com) |
Be careful of the examples you use. They stick(blog.thinkst.com) |
> Updated by: 6761
company-35642.domain.com
printf("Hello World")Yes!
> Going forward, we will show multiple examples of prefixes. A user looking to add a custom domain will see a variety of example zones when they visit the page, and the examples will cycle each time they open the configuration page. We want to convey that they have options in choosing the name, and we show them a variety of sample options. Our hope is that this will prompt customers to pick their own names, and if they do rely on our examples then those are now spread over a large list of examples.
No! They were so close and yet it sounds like they've still missed the point. The issue is that users don't understand the "why" behind the prefix. Just randomizing the prefix that they're shown does nothing to change that.
IMO, a better solution would be. 1. The shortest possible explanation under the field of why you shouldn't use "someprefix". 2. Prevent users from using "someprefix" as the prefix and show them the warning again. By eliminating the default option as an option, you force your users to leave auto-pilot mode and actually consider their choice.
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.
- Go to <link> and get your publisher ID - Add the following line to your config(replacing xxx-xxxx-xxxxx with your code from the previous step):
AddHeader X-Publisher-Id: xxxx-xxxxx-xxxxx;
We had a bunch of people leave the x's in and were confused why it wasn't working. So we made a blog that explained the misconfiguration, and replaced xxxx-xxxx-xxxxx in the documentations with that blog's ID. We got far fewer support requests after that.
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.
The example here is of course slightly different, but I think a similar pattern could be applied.
Yes. That's why https://example.com exists.
$ (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 particularly vocal dev came to me directly and insisted it was broken, so I went on a shared session with him, it turns out they were pasting the "$" into the terminal causing it to say: "$: command not found."
That was the source of all the complaints, once I removed it, they stopped.
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
Another one is can we please stop posting code examples that are illustrating some language feature or how to do thing X in language Y, where the code has a footnote "this isn't secure, don't do this in production code." That footnote will be ignored. If you're going to bother answering a question, answer it with a proper implementation and not something that is a gaping code injection vulnerability.
1. Software is coded to recognize "stupid example values" and prohibit them with an error or at least throw some pretty obvious warnings.
2. Such software also has a rarely-used but documented option to bypass the above checks.
For example, the PostgreSQL server might refuse to allow any DB user to have a password which begins with "password", returning a "Pick A Real One" error.
However somebody somewhere will always need the "don't do that" option: The more different libraries and services you bring together, the more likely there will be either false-alarms or outright conflicts between different example-blocker schemes.
In the very best case, the defaults are so good that an empty configuration does what most people want. Think ripgrep, …, welp, I can't really think of many good examples. Browsers need extensions, Bash needs a decent prompt, even many pro cameras need to be configured to save raw images by default.
On one hand, it prevents blind copy-pasting but on the other hand, your example is invalid.
It isn't perfect, common variable names may already be set or have been set in a previous execution of this playbook on a different problem. But it catches common issues while being convenient.
The takeaway is similar to the article: think very, VERY hard about your examples and sample code. It doesn't just have to be correct and demonstrate the features, it also needs to be fairly robust so that customers don't hurt themselves with it.
For example, if a user is logged in, you can autofill the appropriate accounts/domains/ids/etc to make the example work out of the box; and if some ID needs to be essentially random, then you can make it actually random when you generate the example.
From a simple static page, now you need an API service, most probably connected to a DB or somehow integrated to the rest of your backend. So markdown suddenly isn't enough and you need some server-side logic.
For random strings, you can do this with client-side logic, which in some cases might be easier than server-side logic. But you are still moving from no-logic (static) to somewhere-logic.
as a develoer, is just a nice touch that I can copy paste an example of code snippet and since I'm logged in they can give it to me already with a valid api key.
ymmv
They also allow to output examples in as many langugages/sdk's as you need too
Good examples make documentation worthwhile to read.
Good defaults make an application worthwhile to use.
Can't think of any examples now though I'm afraid.
Dodged a meta-bullet there...
-- Henry Ford
> Hello, could I please apply for the student discount?
>
> [PLEASE READ AND DELETE THIS – After sending this initial message, please attach a proof of your student status, such as a photo of your valid Student ID so we can process this quicker!]
I don't think any of the countless people that have asked for the discount have ever removed the "PLEASE REMOVE" part, and many don't bother to send the proof until we ask for it either.
There was some overlap in these sites w/ respect to IT service companies involved in their setup. Best as I can guess it came down to one person who floated between the employ of a couple (or three) IT service companies leaving a swath of 192.9.1.0/24 in their wake (or maybe training other technicians during their time at these companies). It seems like this work might have been done pre-RFC 1597 (which is, I think, the first place that what is today's RFC 1918 address space shows up) but I think they were just following examples.
I'd love to know what examples motivated the us of this address space. I find some old Sun docs[0] referencing this address space, and RFC 2328[1] makes reference to it.
[0] http://bitsavers.informatik.uni-stuttgart.de/pdf/sun/sunos/3...
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).
Edit: I think it's mildly amusing and further drives the point hom that some people in this thread missed endnote 1, where you say it was not the actual prefix.
This article stresses that it's not a 'customer-side problem', and what they'll do to try to address it on their end.
But is there anything that enterprises can do in order to encourage people not to work blindly from tutorials? What do companies where workers avoid this pitfall look like?
I could kind of tell where this article was going from the first paragraph, but i never thought "some-prefix" would be used by 40%. That is such a high number.
Until the domain was registered and is actively being used.
It’s not around anymore but here’s a discussion of it when it was up:
Why would rust make the presence of bacteria more likely? Is it a food source? No, tetanus on a rusty nail was just an example used in an article many years ago.
Sadly, I cannot find a source for the idea coming from an article at the moment. :/
This is not surprising to me at all. Maybe the authors have never used an example before?
So foo.bar.com or my-subdomain.example.com?
And that is having a function that injects the current user's username into the wiki page. Any instructions that require you to log in as you can then be blindly cut and pasted, without people coming and telling me "it doesn't work" when they try to log in as me. Yeah of course that doesn't work, mate.
People reading runbooks aren't fully engaged. They may actually be in a war room. The moral of this story is that you are not entitled to carve out a chunk of your coworker's attention. Those periods should be brief, and tied to an active initiative/epic. After that 'work' is done, everything you wrote should be something that they can operate at 2:00 am.
Because sooner or later, they well.
$ 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.
I think this is the disconnect. Don't mindlessly copy and paste things. Take the time to understand what's going on.
I used to think it was dumb and annoying.
I partly changed my mind recently, when I found myself copy&pasting lots of quick wiki-like documentation into Markdown fenced code blocks that involved multiple hosts.
Just having the hostname in the prompt reduces the text I have to type in addition to the copy&past, to explain where this command is happening, such as on the workstation vs. one of the servers.
(But it didn't quite help the other day, when I was documenting some self-hosted LLM procedures, and needed to be copy&pasting examples from multiple Screen terminals on the same host, where the prompt didn't distinguish them.)
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.
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.
:$! $CWD $HOSTNAME $;
: (exit status, current directory, hostname, $ or # and a ;
the idea being -- you could just cut and paste and it'd mostly just work (except megabozos who like to make directories named ; or whatnot)
The team lead was like "show us the request in the console", and I opened it up and there was the non-encrypted password, createdAt date and basically all the not-needed properties.
I still cringe thinking about it.
Meh, as a sibling comment points out, it's a demo, it'll happen. And when it happens, it's a teachable moment (assuming you can keep your head together as your demo falls apart before your very eyes): "Ah, so as you can see it's import to set the $DO_NOT_DISPLAY_PLAIN_TEXT_CREDS environment var to 'true', otherwise you get this disaster! Hahaha...ha."
Or if you don't know at the time what's going on, "obviously I'm just getting started on this myself, and need to play with some configuration. Better make sure I do before any of this goes to production! Hahaha...ha."
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.
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.
As in that it should be the default? Or only option? I personally do not have (and want to have) that set, and I am hardly alone. Any change in defaults fucks someone over, especially in things like bash, where you ssh into many machines with many different versions of bash...
Are there examples of projects who solve this well?
Ripgrep's author is also very careful about breaking changes - I think that means it will also one day have outdated defaults!
ripgrep seems to have a major version bump every 18 months or so, which seems a bit excessive. OTOH vim went through 9 versions in 30-something years which seems more reasonable. Although I think there was more churn early on. ISTR vim 6 being around for a long time.
More generally, defaults (including, default examples), matter: https://news.ycombinator.com/item?id=25646180
Especially for software which is mod-able, malleable, composable, configurable... defaults have a disproportionate impact on UX, DevEx etc. A reason why TLS 1.3 got rid of a laundry list of options, or why WireGuard is simply a joy to work with (as opposed to IPsec / OpenVPN), or why middleboxes on the Internet are a big hurdle to protocol upgrades, or how NewCloud companies like Cloudflare, Replit, Flyio, and Vercel have devex beyond what the Big 3 can muster up.
> Think ripgrep ... welp, I can't really think of many good examples.
Apple has got this spot on, across decades. Their products "just work", as they say so in their own marketing.
> Browsers need extensions
Now you see why Chrome is defaulting to Manifest v3 ;)
This sounds completely insane. If a majority of people need something different, they shouldn't be allowed to have it?
Prepare your examples accordingly.
Every single mod I could find (sample size of ~1000) just extended the example.
Alternatively, you’ll have to teach users what kinds of prefixes would be appropriate, with an example which is obviosly not appropriate for any of your actual user. This will take some length of text to explain, and many users will not read it, and may instead abandon your service.
Relatedly, I’ve always disliked when programs force me to name N number of things without adequately explaining
• What the names are (Is this some kind of group name? Instance name?)
• How the name will be shown. (Should I prefix the name with the company name myself, or will that always be visible? Will this name be shown together with numerous other names which are all UPPER CASE? Will the name be automatically converted to lower case?)
• If any of these names will be publicly visible.
• If any of the names can be changed later, and how hard it is.
• What characters are allowed (Are spaces, underscores, or dashes allowed? How about Unicode? Emojis? What is the normal naming scheme?)
• How long is the name allowed to be? (Will it be silently truncated at 8 or 16 characters (or grapheme clusters)?)
So basically it was black because that kept production costs down.
This choice simply baffles me. If I could just use those aliases and have it under the hood be PS calls- that's great! But that's not what's happening, instead it's a totally different command with different a different syntax and different flags. Why make it an alias at all‽
the only thing scarier than seeing your personal “not for prod” code running in prod by someone else’s hand. the “improvements.”
https://en.wikipedia.org/wiki/List_of_Internet_top-level_dom...
"ICANN/IANA has created some Special-Use domain names which are meant for special technical purposes. ICANN/IANA owns all of the Special-Use domain names."
".test" is recommended for use in testing of current or new DNS related code.
".example" is recommended for use in documentation or as examples.
".invalid" is intended for use in online construction of domain that are sure to be invalid and which it is obvious at a are invalid.
The ".localhost" TLD has traditionally been statically defined in DNS implementations as having an A record pointing to the back IP address and is reserved for such use. Any other use conflict with widely deployed code which assumes this use.
test
example
invalid
localhost
local
localdomain
domain
lan
home
host
corp
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.
(another prompt is just an annoyance for no benefit)
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.
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 of, say, coreutils, or glibc, or glib/gtk, or perl, or Qt, etc...) seemed appropriate.
> 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.
A breaking change is going to break someone's workflow. (See also, Hyrum's Law, xkcd 1172.)
As a user and developer, my preference is for breaking changes to be put off as long as possible, and then all applied together every few years or so. (Or never :-) That way, I don't normally have to pay that much attention to updates, even if an app gets new features. But when there's a major version bump, I can check the release notes carefully and know to keep an eye out for anything unusual/different.
If I only ever ran one program, it wouldn't be a big deal. But I don't, I run hundreds regularly. If they all have breaking changes once per year, that averages out to me needing to check over two sets of changes that might impact me every week.
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....
Eliminating the duplicates makes it much easier to search the history for a command that was used long ago instead of having to skip over hundreds of duplicates of some non-interesting command, such as "ls".
It also makes it much more likely that complex commands used a long time are still preserved. No matter how large you make your history file, it is much more likely that it will become filled with simple commands that you do not need to recall from history, instead of keeping the complex commands that you hate to retype.
Moreover, while having a command history is useful to avoid retyping some commands, some may be less willing to preserve a history from which it is easy to discover which have been their exact actions while using the computer, though for this it is preferable to also disable the saving of the history file.
$ cat ~/.inputrc
"\e[A": history-search-backward
"\e[B": history-search-forward
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.
And I want my history untouched, because sometimes I forget how I solved something, go back a few months in my shell history and see the sequence of commands that I've used. I think that's a nice thing to have. And if I ever need history without duplicates, it should be easy to deduplicate it with a simple script.