@carnage4life i’ve also found that a buggy blog post with good SEO can cause support issues for years going forward. People copy the bad code and then wonder why their systems scale poorly years later. I’ve had to privately contact blog authors and educate them.

@carnage4life 🧵

Also consider that technical documentation and examples you publish can be mindlessly mixed and reguritated by any LLM that uses it!

@carnage4life As a consultant, I concur. I have spent endless hours uncovering and helping clients fix problems due to blindly copying sample code instead of understanding what the sample was exemplifying.

@carnage4life I’ve done this, too. When you’re in “just get this done” mode, you really don’t want to learn all about the inner workings of the package/library you’re using. Just the API and how to use it.

By the way, may I add that you are one of my favorite Mastodon posters? Informative and insightful, in areas of interest that happen to overlap mine quite a bit.

@carnage4life
I hate when docs mix random variables and necessary inputs.

Like, how to replace a letter using sed.

Example:
Replace the letter "s" with the letter "g".

$ sed 's/s/g/g'

???

@carnage4life CIS benchmarks get used this way a lot. The example bits of code are simplified for the sake of clarity, and are neither complete nor in some cases safe to run unaltered on production systems.

For example, the sshd configuration checks do not check how sshd is actually configured (trivial, since sshd will happily spit out a full running config), but rather that certain keywords are present in the main config file. Easy to induce false results.

@carnage4life Yes! A classic mistake is when you want to show an example but that requires quite a bit of code to do right, so you show a "simpler" example with a comment "don't do this in prod / implement X the right way". You can bet it'll end up in prod..

I'd point this out, people would say "but it's a lot of code to make an example with the right API usage" to which I would point out "maybe the API isn't right / could be improved / you need to build helper libs"

@carnage4life Very true, I think the pithiest I've heard this put is that "Example code should be exemplary."

@carnage4life@mas.to

The number of times I've caveated a block of text by saying "this is not executable as is" yet have people complain that my instructions didn't work....

@carnage4life I always omit preconditions from examples I use to illustrate a specific point so that if they're reused verbatim they will crash. I expect people to actually read and understand what they're doing. (Obviously the preconditions are spelled out earlier, but later examples only show the code directly relevant to the point being explained.)

@carnage4life

🤔

#ExemplarExamples ?

@carnage4life many years ago I was rolling out SendGrid using their .net library. We very quickly ran out of connections because the actual library wasn't doing connection management.

I filed the bug, but they pointed at the official.net example for using the http client. This was the newest HttpClient that was actually a factory for IDisposable objects. And the text explained that you needed to manage the HttpClient as a singleton, but the sample code didn't actually do that. 🤷‍♂️