# 015: When I Use Videos vs. Docs — The CALE Decision Framework
¡Hola, Tech Writing Friends!
Have you ever wondered… should this be a written doc or a video tutorial?
As tech writers, the decision often lands in our hands.
Let’s break it down with a simple decision framework so you can make the right call every time.
Why Do We Care?
The question of videos vs. written docs is about learning styles and engagement levels.
Written Docs: Ideal for step-by-step guides and reference material, where users can quickly read exactly what they need.
Videos: Great for showing how something works, visually demonstrating workflows or complex interactions. But even though videos are interactive, they’re still passive learning tools.
Because each format has strengths and weaknesses, the best choice depends on your audience and the task.
Video Tutorials: Pros and Cons
Pros…
Excellent for visual learners.
Can demonstrate actions, like navigating a UI or performing a complex task.
Humanizes your brand with a voice and tone users can connect with.
Cons…
Time-consuming to create and update, especially for fast-changing products.
Passive learning: Users often watch without truly engaging or retaining knowledge.
Difficult to search and skim.
Written Docs: Pros and Cons
Pros…
Quick to update and maintain.
Easy to search, skim, and reference later.
Suitable for all users, regardless of internet speed or accessibility needs.
Cons…
It can be intimidating for users new to technical jargon.
Doesn’t provide a “show-and-tell” experience.
Lacks the emotional connection of a human voice.
The CALE Decision Framework: How to Pick
Here’s my simple CALE framework to decide whether to create a video or written doc:
1️⃣ Complexity
Is the task highly visual (e.g., navigating the AWS Console)? Use a video.
Does it involve troubleshooting or multiple steps? Use written docs.
2️⃣ Audience Preference
Are your users visual learners or new to your product? Consider videos.
Do they need quick answers or reference material? Stick with written docs.
3️⃣ Longevity
Will the information change frequently? Go with written docs to save time on updates.
Is it evergreen content (e.g., a welcome message)? A video might be worth the effort.
4️⃣ Engagement Goals
Want to humanize your brand? Use videos with a friendly narrator.
Need to enable users to learn actively? Stick with written docs or combine both formats.
Pro Tips for Creating Videos and Written Docs
For Video Tutorials…
Keep it short and focused (2-5 minutes max).
Write a script beforehand to stay concise.
Use captions for accessibility.
Add timestamps so users can jump to specific sections.
For Written Docs…
Use clear headings, bullet points, and visuals (e.g., screenshots, diagrams).
Include links to video tutorials when applicable.
Blending Videos and Written Docs
Why not both?
Create Interactive Docs. Embed video clips into your written documentation for users who want a visual walkthrough.
Develop Video Summaries. Use videos as overviews, with detailed steps provided in text form below.
Implement Learning Paths. Create a “Choose Your Adventure” style user journey where users can pick between a video or written guide.
Your Next Action Steps
Audit your existing docs: Are there opportunities to add videos or simplify text-heavy sections?
Experiment with both formats: Test user engagement to see what resonates best.
Start small: Add one video to a frequently used doc and gather feedback.
Happy documenting!
Quetzalli
