screen-recording-tool: Draft

capabilities/documentation-quality.md

@@ -37,6 +37,10 @@ Generally, an overall score equal to or less than 3 means you'll likely gain a l
 
 The following is a curated list of supporting practices to consider when looking to improve your team's Documentation Quality capability. While not every practice will be beneficial in every situation, this list is meant to provide teams with fresh, pragmatic, and actionable ideas to support this capability.
 
+### [Introduce a Screen Recording Tool](/practices/introduce-a-screen-recording-tool.md)
+
+A screen-recording tool supports documentation quality by capturing details that text often misses, such as workflows, edge cases, and intent behind decisions. Because creating a video is fast and easy, teams can add clear, high-value context to tickets without slowing down their work. As these recordings become a routine part of documentation, the overall accuracy and clarity of requirements improve, reducing misunderstandings and rework.
+
 ### [Use Documentation Auto-Generation Tooling](/practices/use-documentation-auto-generation-tooling.md)
 
 Automate the creation of documentation using tools that generate comprehensive and up-to-date documentation directly from the source code or configuration files. This practice ensures that documentation stays in sync with the codebase, reducing the manual effort required to maintain it, and minimizing the risk of outdated or incomplete information. Tools like [Swagger](https://github.com/swagger-api) create executable documentation, while tools like [RepoAgent](https://github.com/OpenBMB/RepoAgent) use LLMs to automatically keep the documentation in sync as the codebase changes.

capabilities/learning-culture.md

@@ -60,6 +60,10 @@ Talking directly with users is an invaluable practice for gaining insights and u
 
 Dogfooding your systems involves having your teams use the same products or systems that your users do, allowing them to experience the same pain points firsthand. This practice helps build empathy with users, identify issues early, and drive improvements based on direct "user" experience. By regularly using your own systems as customers would, your team can gain valuable insights and ensure that the product meets the highest standards of usability and performance.
 
+### [Introduce a Screen Recording Tool](/practices/introduce-a-screen-recording-tool.md)
+
+A screen-recording tool supports a learning culture by making it easy to create and share videos that carry far more context and nuance than text alone. When recording becomes effortless, teammates naturally default to richer explanations that help others understand intent, reasoning, and edge cases. As this practice becomes a norm, the flow of high-quality information increases, giving the team more opportunities to learn from each other.
+
 ### [Use SPIN To Unearth Problems and Solutions](/practices/use-spin-to-unearth-problems-and-solutions.md)
 
 SPIN is a question-asking framework that was originally developed for sales professionals. It focuses on understanding a person's needs through four types of questions: Situation, Problem, Implication, and Need-Payoff. Software professionals can use SPIN to uncover problems, clarify needs, and arrive at creative solutions, thus bolstering a learning culture.

practices/introduce-a-screen-recording-tool.md

@@ -0,0 +1,72 @@
+# Introduce a Screen-Recording Tool
+
+An unfortunate reality in software delivery is that tickets are often vague, lack clear acceptance criteria, or rely heavily on assumed knowledge. This leads to frequent misunderstandings, rework, and delays, particularly for newer team members who are unfamiliar with the system or business context. Text-based descriptions often fail to capture the nuance of dynamic workflows, leading to "ping-pong" comments or unnecessary synchronous meetings to clarify requirements.
+
+A lightweight screen-recording tool (such as [Loom](https://www.loom.com/screen-recorder), CloudApp, or similar) allows ticket authors to quickly demonstrate the issue or desired behavior using voice and visuals. This practice reduces ambiguity without adding process overhead. By capturing the visual context and the narrator's intent simultaneously, teams can bridge the gap between "what was written" and "what is needed."
+
+Furthermore, introducing video artifacts into the workflow builds a lasting library of context. Unlike a synchronous call which disappears once it ends, a screen recording attached to a ticket becomes a permanent reference point. This aids in onboarding, future debugging, and creating a more asynchronous, inclusive work environment where team members can consume context at their own pace.
+
+## When to Experiment
+
+- You are a Developer and you need to ensure that your communication is intuitive so that you can document intent more clearly and reduce back-and-forth.
+- You are a Developer and you need to learn how to write tickets quicker so that you can improve the efficiency of handoffs.
+- You are a QA Engineer and you need to demonstrate exactly how to reproduce a bug so that developers spend less time investigating and more time fixing.
+- You are a Product Manager and you need to provide acceptance criteria that show the "happy path" visually so that the team understands the user journey without ambiguity.
+- You are a Team Lead and you want to reduce the number of synchronous "quick sync" meetings so that your team has more time for deep work.
+
+## How to Gain Traction
+
+Adopting video communication can feel awkward at first; many people are self-conscious about recording their voice or screen. To gain traction, the goal is to lower the barrier to entry and normalize "imperfect" videos. You must emphasize that these are disposable, functional artifacts, not polished studio productions. Start small with a pilot group before rolling it out as a team standard.
+
+### Select and Seed the Tooling
+
+Choose a tool that requires zero friction to start recording (browser extensions are usually best). The team lead or champion should "seed" the behavior by recording the first 5-10 updates or ticket descriptions using the tool. When a team member asks a question in chat that requires a complex answer, reply with a short video link instead of a wall of text. This demonstrates the speed and clarity of the medium.
+
+### Embed in the Ticket Template
+
+Modify your issue tracker (e.g., Jira, GitHub Issues) templates to include an optional field for "Video Walkthrough." Explicitly prompting for this encourages the author to consider if a 30-second video could replace three paragraphs of text. Initially, frame this as an experiment: "For this sprint, try to include a video for any bug report."
+
+## Lessons From The Field
+
+- **The Perfectionist Trap:** A common anti-pattern is team members recording a video 5 or 6 times to get it "perfect." You must coach the team that "ums," "ahs," and stumbling over words are acceptable. If the message is conveyed, the video is successful.
+- **Searchability Matters:** Video is excellent for context, but poor for searching. A video should never exist entirely alone; it should always be accompanied by a 1-2 sentence summary or bullet points so that the content is indexed and searchable in the future.
+- **The "3-Minute" Rule:** Videos that drag on for 10 minutes often get skipped. Teams have found success by implementing a soft cap: if it takes longer than 3-5 minutes to explain, it might actually require a synchronous discussion or a written design doc.
+- **Asynchronous Code Reviews:** Teams that attach a short walkthrough video to their Pull Requests often see a drastic reduction in review time. The reviewer understands the "why" before looking at the "how" in the code.
+
+## Deciding to Polish or Pitch
+
+After experimenting with this practice for 2-3 weeks, bring the team together to determine whether the following metrics and/or signals have changed in a positive direction:
+
+### Fast & Measurable
+
+**Reduction in Clarification Meetings**. You should see a decrease in the number of "quick sync" calls required to understand a ticket or a bug report.
+
+### Fast & Intangible
+
+**Developer Sentiment regarding Handoffs**. Team members should report feeling less frustrated by vague requirements and more confident when picking up tickets written by others.
+
+### Slow & Measurable
+
+**Reduction in Cycle Time**. Over time, the clear context provided by video should result in tickets moving from "In Progress" to "Done" faster, with fewer loops back to "To Do" for clarification.
+
+### Slow & Measurable
+
+**Fewer QA Rejections**. You should see a reduction in stories failing QA checks because the initial requirements and the resulting implementation are more tightly aligned through visual confirmation.
+
+## Supported Capabilities
+
+### [Learning Culture](/capabilities/learning-culture.md)
+
+This practice fosters a culture where knowledge is shared openly and accessibly. By recording explanations and context, teams create a reusable knowledge base that encourages continuous learning and faster onboarding for new members.
+
+### [Documentation Quality](/capabilities/documentation-quality.md)
+
+Video walkthroughs significantly enhance the quality of technical documentation by providing high-fidelity context that text alone cannot match. This reduces ambiguity in system behavior descriptions and acceptance criteria.
+
+### [Generative Organizational Culture](/capabilities/generative-organizational-culture.md)
+
+Using video tools encourages high-cooperation and low-friction information sharing. It moves the team away from bureaucratic, text-heavy silos toward a more human, communicative, and bridge-building culture.
+
+### [Visibility of Work in the Value Stream](/capabilities/visibility-of-work-in-the-value-stream.md)
+
+Screen recordings make the actual work and the issues blocking it highly visible. Instead of abstract text descriptions, stakeholders can see exactly what the software is doing (or not doing) at any point in the value stream.