Mary Kate Comer - Removing Unconscious Bias with a Linter

API The Docs Virtual 2022 Recap

This talk was presented at API The Docs Virtual 2022 event series on 16 November. We are glad to present the video recording, and talk summary below. Enjoy!

Visit the talk listing page for an overview of all presentations!

Mary Kate Comer

Principal Software Engineering Lead at Microsoft

Mary's presentation



Q&A

  • I am going to play devil’s advocate. Don’t you think using the name “woke” could be a polarizing term in itself?
  • About a month ago, we had a presentation about the “Inclusive Naming Initiative”. Is Woke being used within that initiative (or vice versa)?
  • Looks awesome and glad to see there are both active and closed Issues on GitHub. What kinds of contributors are you looking for?

Removing Unconscious Bias with a Linter

In this talk, Mary Kate shares a linter to curb the use of non-inclusive language when writing documents or code. The linter provides helpful alternatives, and it can be customized. This helps not only with documentation, but how we speak to each other.

Why inclusive language matters

Words have a direct and indirect impact on those who hear or read them. The smallest changes in the words you choose might cause huge emotional differences.

You have to:

  • be open and willing to learn,
  • be aware that the impact of the words what matters and not the intent behind them,
  • choose wisely where you control the choice of words (e.g., when you’re writing code or documentation).

Inclusive language is designed to avoid excluding people on the basis of gender, sexual preference, age, race, ability, etc. It avoids offensive language, and aims for social justice.

As a professional, you should:

  • promote inclusive work environment,
  • use inclusive language everywhere and consistently.

Categories of inclusive language that you should be aware of

  • Gendered
  • Ableism & Ageism
  • Socially charged language
  • Violent language

An open-source linter to detect non-inclusive language

Woke: A flexible, language-agnostic liting tool that multiple teams and organizations can use. Based on different rulesets, the tool can detect non-inclusive words, and recommend alternatives: - you can add custom rulesets and define terms to lint for, - rulesets are highly configurable and applied at runtime, - you can store rulesets locally or on Github, - check your comments and variable names as well.

Use a CLI, Github action, or the available text editor plugin to leverage the tool. You can run it locally or implement it into your CI/CD pipeline.

After the introductory part of the presentation, Mary Kate demoed the linter.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.