Item — HN Reader

I want to call BS on the statement "Most meetings can be replaced with documentation." Maybe in an ideal world, but no.

Have you tried reading the documentation the average engineer makes? It's like a freshman essay -- lacking in cohesion, vision, context. It's usually completely unstandardized across teams.

And 9 times out of 10 the most fundamental questions aren't answered by the documentation e.g. "Why don't we just use existing tool X to solve this problem?"

Communication is hard. Engineers use buzzwords. Product uses buzzwords. Companies use buzzwords. Combine all these and you get a soup of overloaded terms e.g. "service," "connect," "access," "resource," "platform" that have a wide range of potential meanings.

6 comments

It really depends on the meeting. Meetings that revolve around basic information sharing (typically the recurring ones) like status updates or daily scrum can 100% be replaced with a written update. These are the meetings people hate.

A great meeting is when the right number of people discuss an ambiguous problem that requires a fast feedback loop (body language, tone, etc) in order to achieve the desired meeting outcome.

I'd also argue that poor documentation is a result of lack of structure (something asynchronous communication can provide much better vs. synchronous comm)

This is tongue firmly in cheek, but I think it really drives home your "Communication is hard" point.

Have you tried reading the meeting agenda and minutes the average engineering manager makes? It's like a freshman essay -- lacking in cohesion, vision, context. It's usually completely unstandardized across teams.

And 9 times out of 10 the most fundamental questions aren't answered in the meetings e.g. "Why don't we just use existing tool X to solve this problem?"

Agenda? Minutes? I've heard tell of such a thing, but I've yet to meet a manager that actually performs these arcane acts. I've gotten very used to walking into meetings with no more idea of what's going to happen than I can glean from the participants list and the subject on the calendar item...

Oh, cool, we must work together.

I pushed my team hard to get some discipline around meeting agendas. It lasted for a week or two. I threatened to stop attending meetings otherwise. My Director told me to knock it off. So, the signal is clear, right? We're all just fucking around and playing pretend at being professionals.

Yeah, but the point is, I can ask all of those questions in the meeting if I'm there in person.

You could also read documentation and ask questions about it. And unlike meetings, everyone won't just forget the answer and have to have the discussion next week.

A lot of engineers hate documentation and meetings. It's their managers job to make sure they do the boring stuff that the organisation needs.

If a manager says "remember to do some meetings" at the start of the year then never follows up on ensuring those meetings are actually effective, those meetings might be a waste of time. If they say "remember to do some documentation" at the start of the year and never follows up the documentation will be a waste of time.

If managers are spending more time making meetings a big priority, maybe it's because unlike documentation they get to feel like a real leader because they are running effective meetings. Maybe managers just like meetings more than documentation. Maybe it's higher value to the organisation as a whole, but I doubt it.

You might be right but you also dont seem to be making room for the possibility of improving, learning, and making it easier to write those docs. You dont need to have a blank piece of paper and average engineers shouldnt need to guess how to fill in a memo.

Ah ah! I did and I do. That's why well written documentation is more than a "good to have", it's as important as the code itself, same as good tests.

Communication is always a challenge and no big or small company has fully cracked it for sure. Average engineers - whatever that means - need training and meaningful tutoring. The team should aim at becoming better, not settle for whatever they have at the moment.

> Have you tried reading the documentation the average engineer makes?

Yes. Don't hire the average engineer.

Or raise your bar for average. If communication ability is important to your org, hire some folks to mentor and coach your engineers. Measure them on their communication and documentation abilities, and reward them when they meet or exceed the expected level.

Or be willing to train. It's a tough skill and seems to have few mentors