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,
documentation.
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
into it.
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.
Documentation needs to be discoverable
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
writer.
Turn out, 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 multiple iterations.
It gives you time to actually think through what you’re documenting.
Documentation is living, not immutable
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
changed.
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 search and discovery.
