Hacker News Reader

Comment by strken | Hacker News Reader

I suspect that the presentations and diagrams which need to be made, are made. Good communication is important, but the artefacts come about from the organic need to communicate an idea rather than orders from on high.

Consider "The Bar team wants to know about our new Foo architecture" vs "The Bar team needs a 30 minute presentation on our new Foo architecture". Does the Bar team actually need a presentation, and could it be a live demo? Do they just need better documentation? Are they building an integration, and would someone from your team working with them for a week unblock them in a way a presentation wouldn't? Could this be a ten minute call between you and the one engineer who needs a hand?

Good and experienced engineers do their best work on open-ended tasks. This is as true of communication as it is solo work. Artificially dictating the solution without understanding the problem limits them.

View on HN

> I suspect that the presentations and diagrams which need to be made, are made.

I don't think that's true.

E.g. diagrams are made, once, because of an audit, instead of made iteratively as the software changes.

Or someone says, "If they want to know, they can just talk to me. You know, have a conversation?"

The whole "yeah, just have a conversation" thing bugs me a lot. I like talking, and having conversations. It's rarely enough. The information needs to be written down (or codified in tests or whatever). Future people won't have the luxury of a conversation with whoever originally wrote something. Conversations aren't indexable. Conversations lose nuance, memories fade or get jumbled. Have your conversation, then document/diagram it afterwards.

And it's like talking about code and coding. Once you start writing you find all^W a lot of assumptions/hypotheses you made implicitly or even flaws in your reasoning.

Writing is nature's way of letting you know how sloppy your thinking is.

Plus, conversations are synchronous. If it's just one person explaining to another, it's no so bad. But what if that person needs to explain it to five or ten people? Do you have multiple 1:1 conversations or try to schedule a meeting at a time everyone is available?

The problem is when engineers make presentations instead of writing documentation. The best presentations are when an engineer has written a long page of documentation and walks through it, interspersed with Alt+Tabs to demos of the documented stuff in action.

Too many dysfunctional teams have a culture where engineers make a 1 hour presentation at the end of a multi-week project, upload the ppt and recording somewhere and call it a wrap, without writing a word of searchable and version-controlled documentation.

Yes. Presentations are summaries. There needs to be real documentation that they're summarizing.

Reply on news.ycombinator.com