Write non-technical documentation to create a single point of truth

[marietheresa]

People still on the fence about your change need easy access to all the information you've already shared. They might be trying to determine if your change will impact their roadmap and want to look up the tentative deadlines you put in that e-mail six weeks ago. Or they might want to know if anybody on the team can work on the tasks you defined, and now they want to refer back to that post you made about that last Thursday.

And the less friction getting that information creates, the better off you'll be because their patience trying to get it won't be endless.¹ And when they run out of patience, they'll form an opinion about your change based on the information that they currently have.

But older chat messages are notoriously hard to find.² Forgot what channel something was posted in? Good luck figuring out which of the dozen security-related channels the team uses for announcements.³ Can't remember the keywords in the title of the post you're looking for? Have fun scrolling through every message posted ever in the last quarter. And while e-mails might generally be more accessible, getting information from them is still a pain.

So, it's a good idea to start creating a more permanent form of documentation at this stage. Write everything you know - and even the things you don't know yet but are thinking about - down and then link to that documentation in each of your posts (or e-mail if you must). It will give people a single point of truth to come back to again and again, making it that much easier for them to be informed and follow along.

Footnotes

1. Because humans aren't robots. At some point we just can't anymore. ↩

2. Let's not even talk about comments on posts. Those are just gone. Poof. ↩

3. Yes, that's a fixable problem. And yes, we should do better. ↩