This talk was presented at API The Docs Virtual 2022 event series on 12 October. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit the talk listing page for an overview of all presentations!
Anne Gentle
Developer Experience at Cisco DevNet
Anne's presentation (video recording)
Anne's slides
Q&A
- When somebody comes into Cisco, how do you find the balance and what are you currently doing for this to not be punitive but more like an easy way to absorb this?
- How do you filter out irrelevant or false results (if there are any)?
- How do you explain the need to implement these changes to people/developers, who come from different cultural backgrounds, and treat these terms as technical jargon that has no secondary harmful connotation?
- Do you have to teach your audience to understand the meaning of non-biased terms? Maybe some people aren't familiar with some of them. Don’t they cause any friction?
“We must help bridge gaps of inequity by using our technology, extended ecosystem, and the expertise of our teams, while creating more opportunities for more people, and acting responsibly to drive change.” Chuck Robbins, CEO of Cisco
Human Rights by Design
- Advise & Train Product Teams on Human Rights throughout the Product Development Lifecycle
- Where might the product be hurtful?"
Accessibility by Design
- Advise & Train Product Teams on Accessibility throughout the Product Development Lifecycle
- Can you point a screen reader and get an ability for someone to read the documentation? Can you read a webpage with a screen reader?
Inclusive naming
- Implement Cisco’s Inclusive Language Policy
- Build Employee Awareness about Inclusive Language
- Drive Compliance across Cisco’s Functions
- Engage Community and share Best Practices
- Embed a Culture of Belonging via Governance Models
Inclusive language
- Making sure that the company has an inclusive language policy, the teams know about the policy, the policy can be implemented, and teams have the necessary tools to implement them.
- Driving compliance requires that we know what compliance means - and define the boundaries.
- Being assistive and not punitive.
- Engaging humanity, making sure teams know each other, and knowing what each team tackles.
Policy to Practice
- Goal: promote and facilitate replacing harmful and exclusionary language in tech.
- If you’re a single writer in an organization and you don’t even know where to start, visit the Inclusive Naming Initiative and take a look at the words list.
- Mitigate and make sure these words are not creeping back into your code: automated checks in CI/CD.
Look at these word lists as an API contract:
- Version-locked; users know which version to expect the change,
- Documents the dates to expect the change,
- Backwards compatibility means no breaking changes due to a word change,
- Communicates a roadmap for future word changes.
What else did the team do?
Categorization exercise - Asset categories
- Category #1: Variable names or comments that are internal to code. No impact to customers and no external visibility.
- Category #2: CLI (Actual configuration files), API or schema use. Deprecate the old use, and create a new one with a text alias. This is complex and customer-facing, new and old must work and you have to communicate it.
- Category #3: Logs, telemetry, monitoring: Support old and new (don’t break customer scripts). Deprecate the old but cutover to new.
- Category #4: Documentation changes: Simple cases are easy to do. Complex cases (like documenting a CLI) must follow product changes.
Unintended side effects you need to take care of:
- Sometimes the place where the words need to be changed is not just in the code comments but actually in a standard use - what is your plan to change that?
- It’s not just in the documentation: Docker file, interactive documentation, cascading upgrades that have to happen (e.g., Git, Python).
Product documentation: until the product changes, the product documentation can’t change that word.
New Terms and Impact on Code vs.Culture
- Goal: Centralized governance for policy and language decisions
- Which terms are critical enough to justify a company-wide change in code, and why? And how?
- US vs. Global intake process – Why wouldn’t we include global terms in our policy? Set up a framework so this could be done in non-English languages and for non-English and non-North American cultures.
- Scale – How do we meet all language needs for all roles?
What can you do to advance Inclusive Language?
- Take an inventory of your engineering assets (code, log files, telemetry data, standards).
- Take a moment to reflect on your own use of language.
- Consider what you can do in your role, and with your unique skills,
- Take a Linux Foundation training on inclusive speaking.
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.
