3 ms·
This depends enormously on the culture of your organization. And in a high-level role like this you're in a strong position to shape that culture.
by jefftk 7y ago
This depends enormously on the culture of your organization. And in a high-level role like this you're in a strong position to shape that culture.
- rabidrat 7y agoHow do you get people to read things? I've also written plenty into the void, and have no idea how to get people to actually read things (without being a jerk about it, which is not the culture I want to shape).
- stronglikedan 7y agoWhile I don't make people read things, but if the answer is in something that they should have already read, I do use their questions as a teachable moment. Instead of just giving them the answer, I tell them where to find it. Usually with a friendly note indicating that the docs are usually the quickest way to get an answer. The old teach-a-man-to-fish adage, if you will. Some people never learn, but I'm still not unfriendly towards them. Although, I do start to silently de-prioritize their questions over time. Most people do learn though, and they're the ones that start asking for clarifications instead of complete answers.
- jefftk 7y agoThings I've found useful: * Use a platform where it's very easy for people to give feedback. I've used Google Docs and Quip. * Write documents when there's real disagreement about how something should work. * Ask specific people for feedback on your documents. * Ask other people to write things, read what they write, and leave good comments. * Have a regularly scheduled meeting for reviewing team documents to get feedback. Anyone can sign up with a doc they want reviewed.
- edraferi 7y agoAlso: * Write clearly & concisely * Use good headers and provide a table of contents Here are some useful resources for writing better: https://www.plainlanguage.gov/ https://www.plainlanguage.gov/ http://www.hemingwayapp.com/ http://www.hemingwayapp.com/
- tootie 7y agoI honestly don't think it's even valuable to write them. It's a manifestation of BDUF. The more detail you put into a document up front, the more wrong assumptions you're committee to paper. It's basically a guess. Same reason we've adopted agile as a mindset, architecture needs to be agile too. Documenting a system as it's built is much more useful. For context, I mostly work in consulting. So I don't have a lot of authority to impact culture as much as I try. Doing handoffs is a big part of my job and even if I hand off a detailed explanation of everything we've done, I'm still guaranteed to get asked about everything I've already written down.