Journal tags: documentation

In their rush to cram in “AI” “features”, it seems to me that many companies don’t actually understand why people use their products.

Google is acting as though its greatest asset is its search engine. Same with Bing.

Mozilla Developer Network is acting as though its greatest asset is its documentation. Same with Stack Overflow.

But their greatest asset is actually trust.

If I use a search engine I need to be able to trust that the filtering is good. If I look up documentation I need to trust that the information is good. I don’t expect perfection, but I also don’t expect to have to constantly be thinking “was this generated by a large language model, and if so, how can I know it’s not hallucinating?”

“But”, the apologists will respond, “the results are mostly correct! The documentation is mostly true!”

Sure, but as Terence puts it:

The intern who files most things perfectly but has, more than once, tipped an entire cup of coffee into the filing cabinet is going to be remembered as “that klutzy intern we had to fire.”

Trust is a precious commodity. It takes a long time to build trust. It takes a short time to destroy it.

I am honestly astonished that so many companies don’t seem to realise what they’re destroying.

Harry popped ’round to the Clearleft studio yesterday. It’s always nice when a Clearleft alum comes to visit.

It wasn’t just a social call though. Harry wanted to run through the ideas he’s got for his UX London talk.

Wait. I buried the lede. Let me start again.

Harry Brignull is speaking at this year’s UX London!

Yes, the person who literally wrote the book on deceptive design patterns will be on the line-up. And judging from what I heard yesterday, it’s going to be a brilliant talk.

It was fascinating listening to Harry talk about the times he’s been brought in to investigate companies accused of deliberately employing deceptive design tactics. It involves a lot of research and detective work, trawling through internal communications hoping to find a smoking gun like a memo from the boss or an objection from a beleaguered designer.

I thought about this again today reading Nic Chan’s post, Have we forgotten how to build ethical things for the web?. It resonates with what Harry will be talking about at UX London. What can an individual ethical designer do when they’re embedded in a company that doesn’t prioritise user safety?

It’s like a walking into a jets pray of bullshit, so much so that even those with good intentions get easily overwhelmed.

Though I try, my efforts rarely bear fruit, even with the most well-meaning of clients. And look, I get it, no on wants to be the tall poppy. It’s hard enough to squeeze money from the internet-stone these days. Why take a stance on a tiny issue when your users don’t even care? Your competitors certainly don’t. I usually end up quietly acquiescing to whatever bad are made, praying no future discerning user will notice and think badly of me.

It’s pretty clear to me that we can’t rely on individual people to make a difference here.

Still, I take some encouragement from Harry’s detective work. If the very least that an ethical designer (or developer) does is to speak up, on the record, then that can end up counting for a lot when the enshittification hits the fan.

If you see something, say something. Actually, don’t just say it. Write it down. In official communication channels, like email.

I remember when Clearleft crossed an ethical line (for me) by working on a cryptobollocks project, I didn’t just voice my objections, I wrote them down in a memo. It wasn’t fun being the tall poppy, the squeeky wheel, the wet blanket. But I think it would’ve been worse (for me) if I did nothing.

A few months back, I wrote about how Google is breaking its social contract with the web, harvesting our content not in order to send search traffic to relevant results, but to feed a large language model that will spew auto-completed sentences instead.

I still think Chris put it best:

I just think it’s fuckin’ rude.

When it comes to the crawlers that are ingesting our words to feed large language models, Neil Clarke describes the situtation:

It should be strictly opt-in. No one should be required to provide their work for free to any person or organization. The online community is under no responsibility to help them create their products. Some will declare that I am “Anti-AI” for saying such things, but that would be a misrepresentation. I am not declaring that these systems should be torn down, simply that their developers aren’t entitled to our work. They can still build those systems with purchased or donated data.

Alas, the current situation is opt-out. The onus is on us to update our robots.txt file.

Neil handily provides the current list to add to your file. Pass it on:

User-agent: CCBot
Disallow: /

User-agent: ChatGPT-User
Disallow: /

User-agent: GPTBot
Disallow: /

User-agent: Google-Extended
Disallow: /

User-agent: Omgilibot
Disallow: /

User-agent: FacebookBot
Disallow: /

In theory you should be able to group those user agents together, but citation needed on whether that’s honoured everywhere:

User-agent: CCBot
User-agent: ChatGPT-User
User-agent: GPTBot
User-agent: Google-Extended
User-agent: Omgilibot
User-agent: FacebookBot
Disallow: /

There’s a bigger issue with robots.txt though. It too is a social contract. And as we’ve seen, when it comes to large language models, social contracts are being ripped up by the companies looking to feed their beasts.

As Jim says:

I realized why I hadn’t yet added any rules to my robots.txt: I have zero faith in it.

That realisation was prompted in part by Manuel Moreale’s experiment with blocking crawlers:

So, what’s the takeaway here? I guess that the vast majority of crawlers don’t give a shit about your robots.txt.

Time to up the ante. Neil’s post offers an option if you’re running Apache. Either in .htaccess or in a .conf file, you can block user agents using mod_rewrite:

RewriteEngine On
RewriteCond %{HTTP_USER_AGENT} (CCBot|ChatGPT|GPTBot|Omgilibot| FacebookBot) [NC]
RewriteRule ^ – [F]

You’ll see that Google-Extended isn’t that list. It isn’t a crawler. Rather it’s the permissions model that Google have implemented for using your site’s content to train large language models: unless you opt out via robots.txt, it’s assumed that you’re totally fine with your content being used to feed their stochastic parrots.

After a fun and productive Indie Web Camp, I stuck around Düsseldorf for Beyond Tellerand. I love this event. I’ve spoken at it quite a few times, but this year it was nice to be there as an attendee. It’s simultaneously a chance to reconnect with old friends I haven’t seen in a while, and an opportunity to meet lovely new people. There was plenty of both this year.

I think this might have been the best Beyond Tellerrand yet, and that’s saying something. It’s not just that the talks were really good—there was also a wonderful atmosphere.

Marc somehow manages to curate a line-up that’s equal parts creativity and code; design and development. It shouldn’t work, but it does. I love the fact that he had a legend of the industry like David Carson on the same stage as first-time speaker like Dorobot …and the crowd loved ‘em equally!

During the event, I found out that I had a small part to play in the creation of the line-up…

Three years ago, I linked to a video of a talk by Mike Hill:

A terrific analysis of industrial design in film and games …featuring a scene-setting opening that delineates the difference between pleasure and happiness.

It’s a talk about chairs in Jodie Foster films. Seriously. It’s fantastic!

Marc saw my link, watched the video, and decided he wanted to get Mike Hill to speak at Beyond Tellerrand. After failing to get a response by email, Marc managed to corner Mike at an event in Amsterdam and get him on this year’s line-up.

Mike gave a talk called The Power of Metaphor and it’s absolutely brilliant. It covers the monomyth (the hero’s journey) and Jungian archetypes, illustrated with the examples Star Wars, The Dark Knight, and Jurassic Park:

Under the surface of their most celebrated films lies a hidden architecture that operates on an unconscious level; This talk is designed to illuminate the techniques that great storytellers use to engage a global audience on a deep and meaningful level through psychological metaphor.

The videos from Beyond Tellerrand are already online so you can watch the talk now.

Mike’s talk was back-to-back with a talk from Carolyn Stransky called Humanising Your Documentation:

In this talk, we’ll discuss how the language we use affects our users and the first steps towards writing accessible, approachable and use case-driven documentation.

While the talk was ostensibly about documentation, I found that it was packed full of good advice for writing well in general.

I had a thought. What if you mashed up these two talks? What if you wrote documentation through the lens of the hero’s journey?

Think about it. When somone arrives at your documentation, they’ve crossed the threshold to the underworld. They are in the cave, facing a dragon. You are their guide, their mentor, their Obi-Wan Kenobi. You can help them conquer their demons and return to the familiar world, changed by their journey.

Too much?

Amber and I often have meta conversations about the nature of learning and teaching. We swap books and share ideas and experiences whenever we’re trying to learn something or trying to teach something. A topic that comes up again and again is the idea of “the curse of knowledge“—it’s the focus of Steven Pinker’s book The Sense Of Style. That’s when the author/teacher can’t remember what it’s like not to know something, which makes for a frustrating reading/learning experience.

This is one of the reasons why I encourage people to blog about stuff as they’re learning it; not when they’ve internalised it. The perspective that comes with being in the moment of figuring something out is invaluable to others. I honestly think that most explanatory books shouldn’t be written by experts—the “curse of knowledge” can become almost insurmountable.

I often think about this when I’m reading through the installation instructions for frameworks, libraries, and other web technologies. I find myself put off by documentation that assumes I’ve got a certain level of pre-existing knowledge. But now instead of letting it get me down, I use it as an opportunity to try and bridge that gap.

The brilliant Safia Abdalla wrote a post a while back called How do I get started contributing to open source?. I definitely don’t have the programming chops to contribute much to a codebase, but I thoroughly agree with Safia’s observation:

If you’re interested in contributing to open source to improve your communication and empathy skills, you’re definitely making the right call. A lot of open source tools could definitely benefit from improvements in the documentation, accessibility, and evangelism departments.

What really jumps out at me is when instructions use words like “simply” or “just”. I’m with Brad:

“Just” makes me feel like an idiot. “Just” presumes I come from a specific background, studied certain courses in university, am fluent in certain technologies, and have read all the right books, articles, and resources. “Just” is a dangerous word.

But rather than letting that feeling overwhelm me, I now try to fix the text. Here are a few examples of changes I’ve suggested, usually via pull requests on Github repos:

• The instructions on the AMP validator page.
• The documentation for Tippy.js, a lightweight JavaScript library.
• The documentation for Composer, the PHP dependency manager.

They all have different codebases in different programming languages, but they’re all intended for humans, so having clear and kind documentation is a shared goal.

I like suggesting these kinds of changes. That initial feeling of frustration I get from reading the documentation gets turned into a warm fuzzy feeling from lending a helping hand.

I was nervous as hell before my talk at An Event Apart Seattle. I don’t normally get quite so nervous but it was a new talk and also …it’s An Event Apart! They set a very, very high bar.

Once I got on stage though, I just started geeking out. I was talking about design principles, a subject I find fascinating. I’m hoping that some of my enthusiasm for the subject helped make for a compelling presentation.

It was a whirlwind tour, starting with a long-zoom look at design principles in history before moving on to the web, where I took an up-close-and-personal look at CSS and quite a bit of HTML, before pulling back again to talk about our planet, our solar system and our galaxy. Yes, there was a space elevator.

I mentioned a range of people, organisations and projects that have documented their design principles, but rather than fill up the slides with lots of URLs, I gave just one URL at the start (and end) of the talk:

principles.adactio.com

That’s where I gathering today examples of documented design principles. By “documented” I mean “published on the web.” There are some really interesting principles from disciplines like urban design but as long as they are locked up in books that aren’t addressable on the network, I can’t link to them.

This is a fairly small-scale project so I figured a wiki might be overkill but if you know of any good documented design principles that should be added to the list, let me know