When the Right Change Breaks Four Files: What Selenium's Documentation System Taught Me About Contributor Onboarding

I raised a pull request to improve Selenium's Python documentation. The change was correct. I replaced a lambda workaround with a purpose-built expected condition, cleaner code, better alignment with Selenium best practices, exactly the kind of contribution the project wants.

The reviewer approved the intent. Then pointed out that my change had shifted line numbers across four language-specific markdown files: English, Japanese, Portuguese, and Chinese. Files I did not know existed. Files I had no reason to look at. Files that were not mentioned anywhere in the contributor guide for this type of change.

The PR is still open. The checks are failing. And the contributor guide still does not document this dependency for modification contributions.

This talk uses that PR, and my broader experience raising documentation PRs for Selenium over the past year, to examine a specific gap in how FOSS projects onboard documentation contributors. Selenium's contributor guide documents the line-number dependency system for one contribution type: adding new examples. It does not document it for a second contribution type: modifying existing examples. A contributor improving existing code has no signal that line numbers are affected, no section of the guide to read, and no automated check to catch the cascade before the reviewer does.

The knowledge lives in the reviewer. Not in the documentation. When that reviewer is unavailable, the knowledge disappears.

This talk proposes one specific addition to contributor guides that closes this gap before the first PR is raised rather than after the reviewer catches the cascade, and argues that the gap between instructions that exist and instructions that work is the most underdiscussed problem in FOSS contributor onboarding.

• Why "the information is in the docs" is not the same as "the information reaches contributors"

• How docs-as-code creates dependency cascades that are invisible to contributors who think they are editing text

• The difference between documenting a contribution type and documenting every contribution type

• One concrete addition to contributor guides that makes the dependency visible before the first PR

• Why knowledge that lives only in reviewers is a single point of failure for contributor onboarding