DEV Community


Discussion on: Explain Knowledge Transfer vs Documentation like I'm five

ryanhaber profile image
Ryan Haber

tl;dr: in my mind, knowledge transfer is broader than documentation and valuable because some things don't transfer as easily in writing

  1. I am a professional writer. I write API docs, so I come to coding from that perspective.

  2. Many people have been trained not to read by writing that wastes time: too many words, too little clarity.

  3. Good writing is clear, easy, and explains to users what they need when they need it.

  4. You can generally tell if your writing is working. The test is whether people read it instead of "calling customer support," whatever "customer support" may be in the context. But yeah, if you write a ton of dense crap that requires a PhD in linguistics to parse, burying key facts like Easter eggs, don't be surprised if your "reader" just phones a friend instead.

  5. Some things should not be put into writing. For example, I would not write to a new coworker, let alone put in Confluence, "Don't talk to X because he's a useless waste of life." Even if it were true and however much I'd need to warn the new coworker, such things should not be written.

  6. Other things are more complicated and the writing works best as a reference or an accompaniment to an interactive conversation. This case is especially common when there is little time and a lot to explain.

IMNSHO, tribal knowledge is frustrating and fragile because people get hit by buses, win the lottery, or just forget. Writing is the solution. In my experience, the number one thing missing from most engineers' writing is just a bit of engineering. Good docs have a logical architecture, know their goal, deploy tools, and solve a problem.