Repeat after me, “screenshots are NOT documentation”.
Neither are videos, looms, or animated GIFs.
Links to Google Docs or random websites, better, but not best.
The aforementioned media types are often confused with real, honest to glob,
When you’re asked to document something, you’re being asked to describe it.
You’re being asked to explain it, to demystify the thought process that went
When you throw a screenshot out into Notion (Wiki, Confluence, et cetera),
you’re effectively defining a word WITH the word.
You’re showing the “what” and omitting the “how” and the “why”.
Not just that, all of these different media types, by their very nature, are not
searchable. Regardless of the documentation tool you use, text searching is more
than likely the lifeblood of the system.
Searching is how new folks on your team can discover things on their own.
If you’re just going to throw in a screenshot of a table, none of the data in
the table will be discoverable. When things aren’t discoverable, the purpose of
the documentation has been defeated.
That’s not to say that documentation should lack screenshots, videos and the
like. Quite the opposite. Those things should be utilized as a way to complement
the words being used. They can, and should, be used demonstrably, but never in
place of prose.
Sure, snapping a quick screenshot is quicker and easier. Sure, filming a loom
video and rambling for 15 minutes covers up that you think you’re a horrible
Guess what. Documentation doesn’t need to be the next great American novel. In
fact, the best documentation is concise and straight to the point. Also, writing
documentation makes you a better writer. Writing things out allows for you to do
It gives you time to actually think through what you’re documenting.
More importantly, it allows for other people to jump in and make changes later
on. For all intents and purposes screenshots are immutable. Either you have to
track down the thing originally captured, or you need to fire up an image
editing application to try to make a change.
The change history also takes a hit, since screenshots are just a cut and dry
replacement for another screenshot. If the entirety of something appears
changed, you need to re-read the entire article to try to figure out what
With plain text, and a system that supports showing differences, you can hone in
on the smaller subset of information that has changed, and be on your merry way.
Oh, and that excuse where you put the screenshot in because you’re planning to
circle back to do a full write up later, nobody is buying that. That mythical
“tomorrow” where you’ll knock out your entire backlog isn’t happening.
It’s simple really, stop making excuses and use your words. You’ll come out a
better communicator, and your team’s documentation will improve immensely thanks
to better searchability and discovery.