It's not you. It's the docs.

“It says speechSynthesis.speak returns ‘void.’ What’s ‘void?’”

“It says that? Well…” I tried to think of an answer that was both honest and helpful. I settled on, “some people use the word ‘void’ to mean the absence of a value. For JavaScript code, they really mean undefined.”

Cat, ever focused on the task at hand, took my hand-waving for what it was and continued working on her web application.

But that interaction stuck with me. It wasn’t that the venerable Mozilla Developer Network had some arcane content; the promise of free and open source software (FOSS) is that anyone can fix problems. What bugged me was thinking about if Cat had the question when working solo–how unlikely it would have been for her to recognize that there was a problem, much less report it.

Sure, there would have been a few moments of confusion as she searched for an explanation. And even though she wouldn’t find anything definitive, she’d likely learn about JavaScript’s void operator, assume some relationship, and move on. She’s pretty Resilient that way. Unfortunately, not only would she have internalized a half-truth; it wouldn’t have even occurred to her to report the misleading content to the maintainers.

As a FOSS maintainer myself, thinking about this kind of missed opportunity fills me with regret.

On some level, it can’t be helped. “You don’t know what you don’t know,” as the saying goes. But from studying human-computer interaction, I know that our deference to technology plays a role. People used to joke about how the blinking “12:00” on a VCR betrayed the technological ineptitude of its owner. A lot of folks believed that even though it really only proved how God-awful the interface design of home theater equipment was. It’s too easy to presume wisdom behind sophisticated tech.

On top of that, mentoring new programmers reminds me of how intimidating it can be to approach a project with subjective feedback. Respect for the expertise of others can grow in to a discounting of one’s own experience, especially given the power dynamics between student and accomplished maintainer, and even more so in publicly-visible forums like bug trackers.

There’s plenty that FOSS project stewards can do to help folks get past these hurdles, but in this post, I’d like to offer some advice for newcomers. Whether you’re a developer or an end user, this boils down to two things: having confidence in your experience, and having trust in project maintainers.

This starts whenever you’re feeling confused by the project. Make an effort to recognize this as it happens, and then take a step back to consider the feeling objectively. Easier said than done, but it’s worthwhile even if you ignore the rest of my advice–improving self-awareness like this ought to reduce your stress levels. Hold on to that until you work out the solution. Was the documentation misleading? Would a different wording or framing have been more helpful?

Next, share your idea with the maintainers, including some notes about what tripped you up in the first place. Be courteous (remember you’re probably talking to volunteers), but don’t be shy. The folks who are most expert are also the least able to recognize this kind of problem. A maintainer’s familiarity is a bias. The good ones recognize this and will welcome your perspective with open arms (case in point: the folks at MDN were happy to replace those references to “void”). You don’t need to have all the answers; simply describing your experience will help the maintainers work with you to make an improvement.

One of the many benefits of free and open source software is the documentation that accompanies it. Just like the code, anyone can offer improvements to the docs. As a newcomer, your perspective is especially important. Your lack of expertise might make it tough to speak up, but it’s also an asset–one you’ll lose as you learn the ropes. So please, don’t be shy! Shine some light on those blind spots, and help the person who follows in your footsteps!