tl;dr

If you want your colleagues to find your documentation, make it public. Contribute to an open source project, post on StackOverflow or write blog articles.

A story from the trenches

A couple of months ago I wrote an article about ssh+sudo tunneling tricks. Soon after it, a colleague at my customer asked me for help. I was in a meeting and didn’t see the request. Some minutes later the colleague wrote me: “Nevermind. I found the answer on the web: https://metamorphant.de/blog/posts/2021-03-17-tunneling-rsync-sshfs-over-ssh-sudo/.” Yet another few minutes later: “Wait a sec. That article is written by YOU!”

In that instant I figured out one of the most powerful techniques in reaching your colleagues with documentation: Don’t document stuff in your internal documentation. Hide it in plain sight. Someplace, where Google can find it (or whatever search engine your colleagues use; probably DuckDuckGo).

2 months later…

Only 2 months later I tried to learn how the heck you can run the awesome backup tool bup on Ubuntu 20.04 and searched the web for a solution. You know what I found? My own blog article. I completely forgot, that I already solved that problem in the past.

And the moral of the story is: Your future self is audience enough to justify documenting in public.



Post header background image by vinsky2002 (Vinson Tan) from Pixabay.


Contact us