Live data from Hacker News

High-documentation, low-meeting work culture

tremendous.com

81–90 of 524 posts

Re: High-documentation, low-meeting work culture

#81

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…

Very much my experience too.

People need to actually learn how to write and maintain(!) documentation, otherwise it’s just a huge chaos.

Rule 1: less (text) is more.

Re: High-documentation, low-meeting work culture

#82

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…

> Confluence There's your problem. The only use case for Confluence is when you want to hide information, but credibly claim that it's documented.

I'd take confluence over google docs because of how bad Google Docs' search is surprisingly

Re: High-documentation, low-meeting work culture

#83

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…

This is why I find documentation to be either useless or actively detrimental. Your documentation is the code. Unless you have a dedicated technical writer on the team whose full time job is to work with developers to document their code, it all just becomes an outdated confusing mess immediately.

Obviously this doesn't apply to public facing codebases. But trying to keep an internal codebase documented, other than fully finished self contained library level code, is a sisyphean task.

Re: High-documentation, low-meeting work culture

#84
post #74

Earlier quoted context omitted.

What is an example of that working? Just code that speaks for itself? How would you ever know why something was done?

You ask someone in slack. If that isn't sufficient, set up a small 1 on 1 meeting to discuss. You can't avoid all meetings, but you can keep them few and small.

Now my ability to find something is limited by someone else's availability, and everywhere I've seen this culture it's devolved into the same 1-2 people answering all the questions as not everyone has a built up map of who knows what.

Re: High-documentation, low-meeting work culture

#85

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…

I think it's important to realize that a lot of documentation is duplication. It duplicates something expressed in code, in configs, in structure, in people's heads, or in the real world.

Duplication can be useful. But the more of it you have, the greater the maintenance burden is. (The main exception is documentation that is not supposed to be kept up to date, like a daily journal or blog posts.) So I think it behooves people to be very careful about adding documentation. Because as you say, it can turn 1 problem into n problems.

Re: High-documentation, low-meeting work culture

#86

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…

This is why I find documentation to be either useless or actively detrimental. Your documentation is the code. Unless you have a dedicated technical writer on the team whose full time job is to work with developers to document their code, it all just becomes an outdated confusing mess immediately. Obviously this doesn't apply to public facing codebases. But trying to keep an internal codebase documented, other than f…

that's ok. but expect your onboarding to take a really long time.

Re: High-documentation, low-meeting work culture

#87

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…

Do we work for the same company? :P Confluence has been the bane of my attempts in finding any relevant docs. Which one is the source of truth? Which one was a draft written by an overly eager to make a first impression, new employee (who is no longer with the company)? Don't even get me started on saving meeting notes to confluence. These days, I maintain my own knowledge base on Obsidian. If there's ever any confus…

So you are now the gatekeeper?

Re: High-documentation, low-meeting work culture

#88
I tried to create this type of culture at my last gig, where I had the unusual privilege of being able to hire almost the entire engineering team, alongside my manager who was also very document oriented. Unfortunately, it didn't work out. Maybe Tremendous has done tremendously better, it's certainly possible, but here is a list of things that went wrong, maybe it's useful.

1. Standard interviews don't assess reading/typing speeds. If you want a high documentation culture this is critical. It took way too long for us to figure this out but many people in the company were significantly slower at reading/typing than us; they found long documents overwhelming and would find excuses to not read them. Slack conversations became a massive sore spot because unknown to us some people felt like they couldn't keep up. They'd try to type a question or response and we'd already posted another two paragraphs before they got a chance to finish their thought. They'd complain to each other that if they asked us a question they got back an essay in response, etc.

2. Documentation requires ownership, otherwise it rapidly becomes useless. Standard corp tooling like wikis doesn't make such workflows easy. They are however optimal from a corp politics perspective (dispersal of responsibility). Maintaining markdown based websites works well as long as you have empowered maintainers who view document quality as a core job function, but you have to force people to submit changes by e.g. rejecting at code review time changes that don't update the docs. People will moan. They will ask you to do it for them. They will submit absolutely min-viable docs changes, they will demand you hire technical writers even if they're easily capable of doing it themselves. And of course the moment you're not using a git-style workflow, just forget it, you have no chance of preserving coherency in any sort of knowledge base.

3. Lots of people aren't just slow but actively HATE reading and writing. They will make things up on the spot, or lie, or just flat out refuse to do the work rather than sit down and read a long document. Jeff Bezos has said about why Amazon uses meeting time to force people to read the memo:

"If we don’t, the executives, like high school kids, will try to bluff their way through a meeting"

You will have to fire people for refusing to read things if you're serious about creating and maintaining such a docs-oriented culture, which in practice is so unpleasant nobody ever does it and so maintaining such a culture is nearly impossible. You will also have to flat-out refuse to meet people in order to force them to read, because otherwise they'll receive a document and just ignore it. I had several cases where one of my most senior engineers would assert that a product we used didn't have feature X, and I had to correct him by pointing out that the user manual discussed feature X in detail. I knew this because I'd actually read the user manual cover to cover. Basically nobody does this and guess what, if you're the one person on the team who reads stuff then you're going to come across as the awkward smart alec who makes people look stupid. Sometimes, ignorance is bliss.

Re: High-documentation, low-meeting work culture

#89

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…

It's actually hilarious how Google - a company famous for it's search engine - made Docs, who's search function cannot find anything.

Re: High-documentation, low-meeting work culture

#90

My current employer was sold to me as a "high documentation" place. What it means in practice is that if you're trying to do something there are 5 outdated documents describing the decision making process for how the project was run, and no documents about how to actually use the resulting software. Occasionally if you ask how to actually do a task in Slack someone will yell at you that you should have searched for a…

I work in medical devices so we have to write a lot of docs. But they all disappear in document management systems where you can't find anything if you don't already know where it is. Are there no document management systems that are actually useful?

Ask yourself how many document management systems are selected after rigorous tests of actual usage vs those selected after sales presentations and schmoozing. That should give you your answer.

And if that's ambiguous, then ask how often your company penalizes people for making the common but wrong choice versus the uncommon but wrong choice.

Post reply on HN