Discussion about this post

User's avatar
Zbyszard's avatar

While this article appears to be an opinion, a Strong one, but still just an opinion. So there is a contr-opinion of mine:

There are two types of documents that you can create: fire-and-forget and maintainable ones. Both of them have a drawback of their own. If you are creating documents with the intent of it being alive and actual all the time, then someone must spend effort updating it regularly. This activity is scaling with the number of documents, so at some point, someone needs to spend a significant portion of the day updating documents. Usually, this cannot be just a person hired for this purpose, but someone with actual knowledge on the topic.

On the other hand, creating documents that won't be updated is quickly generating A LOT of entangled documents, which become a horror for someone to find the information that they need, and even worse for someone who does not know what information they are searching for, but just wants to get holistic knowledge over the topic. If you have 2000 pages of documentation about your project, then good work, you have a lot of text that few will read, and fewer will understand.

Another point that the author raised is to overcommunicate to increase visibility and get to the people that does not read everything. I understand this perspective, but we should ask why people that does not read everything do it in the first place. As a selective reader myself, I can answer this - because it is overhead, most of the information in Slack or email is not useful for me, and well, is overshared. So if one is going to follow your advice, then others, like me, are going to mute even more Slack channels - it's like an arm-war between these two approaches. And casualties are the ones who do read everything, because they have to read even more.

Do I have a solution on my own? No :). My current approach is to keep documentation at a bare minimum - just enough for a person new to the topic to be able to get through all of it in half an hour. The rest of if I prefer to pass in the conversation to ensure that knowledge is fresh, pass in a form aligned with the reciever and context dependend.

Expand full comment
Saurabh Dashora's avatar

Incredible tips Fran.

Some of the same things I came across when I transitioned to senior roles. It's so easy to just say that I know all of this stuff, but none of it is useful when you've to deliver it synchronously. Also, the bit about adapting to the audience is spot on. The approach you follow to explain something depends a lot on the intended readers.

Also, thanks for the mention!

Expand full comment
2 more comments...

No posts