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.
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.
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.
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)?)
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?
> Updated by: 6761
company-35642.domain.com
printf("Hello World")