4 min read
Video or written guide? Picking the right format for each task
Some tasks are best shown and some are best written down. Here's how to decide, and why the strongest documentation often offers both.
By The Primordio team
“Should this be a video or an article?” comes up in almost every documentation project. The honest answer is that it depends on the reader and on what they are trying to do at that moment. The same person might want a video on their first day and a written checklist six months later.
Here is a practical way to decide.
Start with the reader’s situation
Before choosing a format, ask two questions.
Are they learning or looking something up? Someone new to a product is building a mental model. They want to see how the pieces fit together, and watching someone else use the product is a fast way to get there. Someone who already knows the product usually wants one specific answer, as quickly as possible.
Where are they when they need help? A person following along in another window can pause and switch back and forth. A person on a phone between meetings, or in an open office without headphones, might not be able to watch or listen at all.
When video works best
Video is at its best when how something is done matters as much as what is done.
- First impressions and onboarding. A short video tour helps new users get their bearings: where things are, what the main screens do, and what a finished result looks like.
- Multi-step workflows with visual cues. Dragging, arranging, or anything where the movement itself is the instruction is often clearer when you can see it.
- Showing the outcome. Seeing the end result first gives readers a goal and helps them know when they’re done.
- Building confidence. Watching a task done calmly, from start to finish, makes it feel achievable. That matters for tasks people find intimidating.
Video’s weak spots are just as clear. It’s hard to skim, hard to search, and frustrating when you only need step six of nine. It’s also the format most expensive to keep up to date. When the interface changes, a video can’t be quietly edited the way a paragraph can.
When written guides work best
Written documentation shines when the reader is in control of the pace.
- Reference and lookup. Settings, options, limits and permissions are things people look up, not things they watch.
- Skimming for one step. Headings, numbered lists and bold labels let a reader jump straight to the part they need.
- Search. People search for their problem in their own words. Text gets found; a fact buried at 2:41 in a video usually doesn’t.
- Copying and pasting. Anything the reader needs to copy, such as values, commands or addresses, belongs in text.
- Low-bandwidth situations. Text loads fast, works without sound and is easy to translate.
The weakness of written guides is that they ask the reader to translate words into actions on a screen. When the interface is busy, or the task depends on noticing something visual, that translation can be where people get lost.
A simple decision guide
| If the reader needs to… | Lean toward |
|---|---|
| Get oriented in a new product | Video |
| See what “done” looks like | Video |
| Follow a visual, multi-step flow | Video, with a written version |
| Find one specific setting or value | Written |
| Copy something exact | Written |
| Troubleshoot an error message | Written |
| Review a process they already know | Written checklist |
The best answer is often both
For core workflows, the strongest documentation offers both formats side by side: a short video for people who want to watch, and a written guide with the same steps for people who want to skim, search or copy. Each covers the other’s weakness.
The catch is maintenance. Two formats can mean two things to keep current, and they can drift apart. The video shows the new layout while the article still describes the old one. A few habits help:
- Write one script. Treat the written steps as the source and make the video follow them, so the two can’t disagree about the order of things.
- Use the same names. If the article says “Workspace settings”, the narration should say “Workspace settings”, not “the admin page”.
- Update together. When a workflow changes, update both formats in the same pass, or note clearly which one is current.
- Caption everything. Captions make video usable without sound, help non-native speakers and give the video a text track of its own.
A quick checklist
- You know whether the reader is learning or looking something up.
- Onboarding and visual workflows have a short video.
- Reference material, settings and anything copyable are in text.
- Core workflows offer both formats, built from one set of steps.
- Videos have captions and use the same terms as the written guide.
- Both formats are updated in the same pass when the product changes.
Choosing a format is really about meeting people where they are. Offer the one that fits the moment, and offer both where it matters most.