Mastodawn

mhoye Sep 2, 2023

Re: this earlier post: https://mastodon.social/@mhoye/110991950899025738

One of the things I'm most proud of in my last gig was adding notes to our getting-started docs saying explicitly "if this process fails for you, this is a bug and we want to hear from you."

Granting explicit permission to file bugs against the _get-involved process_, quickstart docs particularly, is another way of saying "we care about the details of the experience of getting involved in this project and community", and it is very powerful.

UnseenAcademical Sep 2, 2023

There is such a thing as community accessibility, of the ergonomics of getting involved. It is _extremely common_ for smart, determined people to hit failure after failure during an install process, and decide this project or community just isn't for them. Open Source projects often end up self-selecting for people who coincidentally have not just hardware or software but _cultural expectations_ identical to the primary developers, because all of those failures are completely invisible.

mhoye Sep 2, 2023

As one example - a bunch of our docs said "copy and paste this command:"

> command whatever blah

... and people were copy-and pasting "> command", with the caret and it was failing because of course it was.

Absolutely trivial to fix, but a completely invisible non-problem to anyone who's grown up in a console. But what designer, or technical writer, or translator or or or, would reflexively understand the problem wasn't them?

mhoye Sep 2, 2023

How many people showed up wanting to contribute, and bounced off that bug or any one of a thousand bugs like it? We don't know. There's no way we _can_ know.

But if we put a header right at the top of the docs saying "if this doesn't work for you, we care about that and we want to hear from you" - then suddenly you're on the path to CI/CD _for your community_, not just for your code. Social permission to, and a safe path for, non-community members to start joining is important.

mhoye Sep 2, 2023

Or, put differently: a question we can ask - and as community managers and leaders a question we should be asking ourselves all the time, is:

"Where, in my community, are failures silent or invisible, and crucially, why? How can I make it not just safe and accessible but valued and praised, to change that?"

I think about this a lot.

Greg Wilson Sep 2, 2023

@mhoye returning to @grimalkina's recent blog post (https://www.drcathicks.com/post/on-craft), I wonder how often people don't even get as far as trying to install things because they way we talk tells them they won't be accepted as "real". And yeah, I'm using "we" deliberately there... 😞

On Craft

My grandpa -- my Missouri grandpa, who played slide guitar to me when I got homesick on the rare occasions I stayed with them -- grew up on a farm without electricity. He went past eighth grade, which really mattered to him. He loved that I played harp, which he always called "elegant," in an extremely Missouri accent, an accent that hugged every syllable. Since living in California, I never hear this way of speaking. Recently I heard his accent on TV and cried unexpectedly, ugly crying, startli

drcathicks

Jeremy Kahn Sep 2, 2023

This is even an issue in teams without "unpaid community contributions" —

my team of subject-matter-experts for guardrailing AI systems was smashing into horrible regressions while simultaneously being held responsible for quick turnaround patches (while partners merrily release on an unpredictable schedule)

But the SMEs didn't even know a CI/CD system was _possible_

It was a huge impact, treating the SME content as a product that deserved its own CI/CD system

Jeremy Kahn Sep 2, 2023

@mhoye but the SME grief was _always_ happening silently — cultural assumptions were that the SMEs were just "expected to be scrappy" and doing huge amounts of manual QA

adding CI/CD automation was _easy_ but nobody had thought of it because the SMEs crappy developer experience was ignored by the org — even the SME org

At some level this is about giving the authority to "non-central" devs to say "my problems matter"

Liz Hare PhD Sep 3, 2023

@mhoye this is so good, because people who have been historically excluded have also been taught not to ask for accessibility.

Jon Udell Sep 2, 2023

@mhoye I think about this all the time. What rarely if ever happens: the author of the doc is forced to watch a designer/writer/translator fumbling around making those mistakes. Or the creator of a web app is forced to watch people trying to enter phone numbers into forms. Or really any designer or builder of a product is forced to watch people struggling to use it.

I'm not talking about focus groups. I'm talking about chaining builders to chairs, gagging them, and making them actually watch.

mhoye Sep 2, 2023

@judell My friend Blake once said this about the critical importance of not just user feedback, but actually watching humans use your site or tool or thing or whatever. His line was, "you'd think to yourself, users do what? But then you find out they do nothing _but_ 'what'. 'What' is 90% of all they ever do."

Jon Udell Sep 2, 2023

@mhoye Ideally of course the developer /is/ a user. That works out beautifully for programming tools but not much else.

Paul English once told me that he made the Kayak devs rotate through front-line customer support so that, the nth time they heard the same complaint, they'd be like "Screw this" and just go fix it.

mhoye Sep 2, 2023

@judell I disagree that devs-are-users is a net good. My experience is that it can just as often mean “muscle memory forms to work around problems I don’t want to own” as it can to ownership.

That said, I strongly agree that devs should be required to spend time subjected to the same things they imposed on other people. If Facebook engineers had to spend three days a quarter doing the moderation work they foist off on contractors, the world would be a much better place.

Elias Jachniuk Sep 2, 2023

@judell @mhoye working on a small company as a dev means that I also deal with customer support all the time and this makes me end up fixing a lot of small annoyances that would otherwise be left there for a long long time

mhoye Sep 2, 2023

@lilongueti @judell The core insight of "devops" as a practice, before it morphed into "service contract management through a console" - was that if you have to carry the on call pager for the software you wrote, you write better software. I've long believed the same is true of front line support, and that if anyone in the org takes support calls, the people who wrote the code should spend a few days every quarter doing the same.

Jeff Miller (orange hatband)Sep 3, 2023

@mhoye The project director for a previous job led the devs on a tour of the support group office across the street to ensure that we got the point about usability, especially after seeing how much ad-hoc tooling the support staff used as workarounds for bad support UI.

Jennifer Moore 😷Sep 2, 2023

I often think of Reaper in this context (music software). The way you can use the mouse wheel to expand the timeline, the ease of setting up keyboard shortcuts, the way there nearly always is a way to do the thing that you logically might want to do. I definitely have the vibes that there's a link between that smoothness & its coders (or at least some of them) using it for their own music.

Jon Udell Sep 3, 2023

@unchartedworlds @mhoye Yeah, when the developer happens to be a user scratching their own itch it makes a huge difference.

Jeff Miller (orange hatband)Sep 3, 2023

@judell @mhoye Federated Wiki's meeting today discussed how effective video game onboarding is, as a model for embedded tutorials and skill transfer. (and embedded bug reporting!)

We presume dev-as-user to some extent but there are cases like collaborative coursework better matched to a gentle and direct introduction to how things work.

Richard Hendricks Sep 2, 2023

@mhoye @judell This was a fascinating view from someone having his non-gamer wife try to play some popular games. It's interesting how she approached problems outside the box of the devs preconceived notions and how an experienced gamer would expect. Not offering any help really opened his eyes on how weird some game mechanisms really are.
https://youtu.be/ax7f3JZJHSw?si=CA2KmXWEukXVMYgc

What Games Are Like For Someone Who Doesn't Play Games

YouTube

JaySinWA Sep 2, 2023

@judell
Safeway Driveup & Go here used to have paper forms to fill in ID for alcohol, They kept saying they would have a better way to do it. Yesterday was that day. They had the delivery person enter the data manually on a small tablet. They apologised for the time it took to enter, and then I had to "sign" with my finger as a stylus.
Yep, the designer should be out there tied to the delivery cart.

Garth Kidd Sep 2, 2023

@judell @mhoye yeah that’s how I used to run usability tests on some software for which I was lead dev and de-facto PM. I’d watch a user try to reach their goal, listen to them mutter, and STFU unless they asked for help. Three results:

I’d get as many notes as I could take in twenty minutes, without fail.

My UX design skills improved. My trust in them didn’t.

We kept finding interesting gaps between the goals of the users and those who wanted them to use it.

Baldur Bjarnason Sep 3, 2023

@judell @mhoye At the risk of being a “reply guy”, the UX/UI design industry calls this “exposure hours” and it’s both been a fairly standardised process and common recommendation for improving UX for over thirty years. It’s almost always a non-starter with management, though.

Here’s a decade-old article that talks about this in terms of field visits. https://articles.centercentre.com/user_exposure_hours/

Probably easier to do today with modern tech. Still a non-starter for most managers, though.

jadeforrest Sep 3, 2023

@baldur @judell @mhoye one approach that is fairly lightweight is session recording. I interviewed a eng leader who started the week by having his team watch a few selected session recordings. Not as good as exposure hours (which I can corroborate as an established practice — learned about them 25 years ago). But still pretty good.

@baldur @judell @mhoye in game development, at the studios i've worked at the past 20+ years at least, not doing this would be considered foolish in the extreme. in software dev terms we're constantly making up new user flows and custom interfaces (while also juggling any number of subjective/aesthetic goals) and seeing how people (within the team, outside the team, outside the studio) interact with them for the first time is where your plans meet reality.

@baldur @judell @mhoye and i say that very much not to say "look at how smart we are" - game dev is a mess, haha - but because we live and die by everything that falls under the user experience umbrella, for any given game if we screw up badly enough our audience walks away forever.

Jon Udell Sep 3, 2023

@baldur @mhoye If any of the crappy business websites I've cursed at lately really did follow that recommendation, I shudder to think what they'd have been like if they hadn't!

Baldur Bjarnason Sep 3, 2023

@judell @mhoye Like I said. This is a standard recommendation and there’s tons of data to prove that it works, but you practically never get it past management so very few companies actually do it. At least, in my experience.

Ward Cunningham Sep 3, 2023

@judell @baldur @mhoye
Useability? Just try tuning in the ball game on the hotel TV.

Garth Kidd Sep 2, 2023

@mhoye … it’s beside your point for this thread but… hey it’s that separation between content and presentation again, like in that wonderful rant you were sharing the other day https://siderea.dreamwidth.org/1819759.html

Captcha Check

Julia Evans Sep 3, 2023

@mhoye i was chatting with a friend about how installing programs is hard recently and it turned out they were confused partly because they didn’t understand what PATH did

I was so mad that no project they used ever included a pointer to an explanation of PATH in its install instructions

Robotistry Sep 3, 2023

@b0rk @mhoye Every time I have to change PATH, it's at least an hour of "how do I do this again" and working through searches and OS versions and different instructions to figure out precisely which file/terminal command I need to use to find what it's currently set to, how to read it, what needs to be changed, and how to change it.

With my long covid cognitive exertion limits, anything that requires me to modify PATH manually is now officially not worth the trouble.

Julia Evans Sep 3, 2023

@robotistry @mhoye this may or may not help but I just wrote this to try to answer some of those questions, thank you for writing them down https://wizardzines.com/comics/path/

PATH

wizard zines

Robotistry Sep 3, 2023

@b0rk @mhoye Thank you! Now I just need to be able to find it when I need it!

mhoye Sep 3, 2023

@b0rk I frequently wonder what we could reconsider, if we started a new, human-cantered Unix from first principles. File system perms are at the top of my list, but path ordering isn’t far behind. I mean, it’s really just a namespace from before we knew how to make namespaces work? Surely we can do better?

Chuck Skoda Sep 3, 2023

@mhoye I felt this trying to get started testing Golang for a project. Quickly and repeatedly felt like the community didn’t actually want outsiders. Passed on giving it a try.

Yoshi Carroll Sep 3, 2023

@mhoye What excites me most about #ChatGPT is that it is effective at improving the accessibility of technical communities by specifically addressing these kinds of problems.

For the technologies and domains where it works well, it’s a better startup buddy than a human because it’s always available, it’s infinitely patient, and it never scoffs at me for asking dumb questions

Ninad Pundalik Sep 3, 2023

@mhoye this reminds me of one of @whack's guiding principles (not sure if he viewed it that way, but was definitely to me): If a newbie has a bad time, it's a bug.

Jordan Sissel Sep 3, 2023

@ni_nad @mhoye ++ exactly this! Explicit permission at the very beginning to report bad experiences and acknowledgement from an authority that those reports are desired, respected, and will result in action 👍👍