Josh Sherman
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.
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.
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 multiple iterations.
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 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 searchability and discovery.
