mhoyeSep 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.

Show threadmhoyeSep 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.
Show threadmhoyeSep 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?

Show threadmhoyeSep 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.

Show threadmhoyeSep 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.

Show threadJeremy KahnSep 2, 2023

@mhoye

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

Show threadJeremy Kahn

@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"

Sep 2, 2023 at 6:23pmWeb