Closing the Knowledge Gap

Barry Warsaw

October 2022

About Me

• Core Python developer since 1994
• Former Python Release Manager
• Member of Python Security Response Team
• Founding member Steering Council (3 terms)
• PSF Fellow
• Former project leader for GNU Mailman (and Jython)
• Ubuntu/Debian developer emeritus
• LinkedIn since 2017, TL Python, Knowledge Eng

Why this talk?

• Open source vs Enterprise engineering
• Technical decisions shaped by constraints
  • Organizational
  • User requirements and acceptance
  • Engineering environment
  • Resources
• Strong opinions, informed by principles, tempered with an open mind
• Take intelligent risks

Problem Statement

Top developer pain point:

"I cannot find the technical information I need to do my job effectively and efficiently."

Problem Statement

Is this because the documentation...

• doesn't exist?
• cannot be found?
• is incomplete?
• is stale?
• is duplicated/uncertified?

Close the Knowledge Gap

• Discoverability
• Scale tribal knowledge
• Publishing guidelines
• Metadata, metrics, feedback
• Virtuous cycle b/w producers and consumers
• In-flow proactive help

Close the Knowledge Gap

• Address discoverability through partnership with enterprise search team
• Tribal knowledge is unscalable
• Guidelines for where to publish different kinds of knowledge
• Metadata, metrics, feedback
• Virtuous cycle b/w producers and consumers
• In-flow proactive help

In-repo documentation

• Keep docs close to the code
• Treat docs as code
• Provide team/product landing pages
• Reduce friction for publishing
• Improve UX for consuming

DocIn

What's the problem?

• Closely tied to Gradle
• Kafka events get lost
• Samza process dies
• Artificial Kafka event required
• iframed into deployment portal
• Significant delays and outages
• Complex, high maintenance system
• Inflexible - Sphinx only

Goals of In-repo NG

• Independent of the build system
• Transparent, scalable, sustainable
• Golden path builders w/escape hatch
• Extensible and flexible
• Familiar GitHub workflows
• Incrementally adopt GitHub platform

Reduce friction

for producers and consumers

GitHub Pages

Barry Warsaw

barry@python.org

bwarsaw@linkedin.com

@pumpichank

github.com/warsaw

gitlab.com/warsaw