Hacker News Reader

Comment by jefftk | Hacker News Reader

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.

View on HN

I 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.

I'd much rather have a clear record of the assumptions made & rational for them than have to discover them later when problems crop up.

Agree this is probably the most beneficial application. You can reference it almost like a contract.

How 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).

While 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.

Things 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.

Also:

* Write clearly & concisely

* Use good headers and provide a table of contents

Here are some useful resources for writing better:

https://www.plainlanguage.gov/

http://www.hemingwayapp.com/

Reply on news.ycombinator.com