03-18, 12:05–12:35 (Europe/Paris), VIP Area
Markdown is something you are already using. But do you colocate your internal docs with code? We will unpack how to use open source to record and share tribal knowledge buried in your team's bash aliases & histories – ensuring code and internal docs will no longer diverge.
We'll illustrate how Notebooks, Devcontainers, Web Components, and the VS Code platform, first conceived for analysis, excel at delivering runnable internal docs, reliably describing your team’s tasks, workflows, and solutions. An IDE for Ops is a human-centric approach that isn’t mutually exclusive with CI/CD.
We will learn:
1. Open tech applied for shareable and reliable docs via notebooks
2. How to bridge terminal, browser, and editor
3. Complementary nature with existing best practices
This approach paves the way to DevX & OpsX equilibrium. Allowing devs to trust abstractions (pipelines and internal platforms) while teams owning them benefit from the transparency of runnable docs' self-documenting properties.
Since the rise of the Docs as Code approach, with tools like Python’s Sphinx, Jekyll, Mkdocs, Docusaurus, and rustdoc, we've seen improved frameworks and communities helping us consistently deliver high-quality external documentation.
However, what about your team’s internal docs? The docs your team relies on to develop, test, and break/fix infra, services, and do development daily? In practice, efforts to “fully script everything” fall flat, and written internal docs - a snapshot in time - are quickly outdated. Fully scripting everything (inside and outside pipelines) isn't just complex. It's often brittle, too. Especially the closer automation gets to the engineer; human interfaces starkly differ from uniform machines.
This talk emphasizes the need for improved internal documentation. Documentation needs to clearly explain the WHAT and WHY, while also providing a step-by-step HOW, allowing contributors, developers, and users to better understand key aspects such as:
- The purpose of different technologies and services
- Navigating various platforms for project management and collaboration (like GitHub, GitLab, etc.)
- Identifying personal/service credentials and user-specific configurations
- Determining where and when to run scripts or pipelines, etc
This approach paves the way for effective knowledge sharing. Traditionally, teams rely on intensive onboarding to acquire project-specific knowledge, without formal training or prior experience. Any existing documentation, if available, often becomes outdated quickly. Join this session to explore a better approach to maintaining up-to-date, user-friendly, and runnable documentation that spreads know-how instead of allowing it to fall into the realm of tribal knowledge.
Co-creator of Open Source Runme - DevOps Workflows
Built with Markdown
Sebastian's been involved in deep tech for two decades now. He's helped pioneer browser test automation (Sauce Labs) and advanced cloud-native PKI (Smallstep), and he has now found his passion in unlocking runnable knowledge bases for teams.
A German national living abroad in the United States, he's thrilled to speak at a conference on European home turf about how to "fix" internal docs once and for all.