Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

High-documentation, low-meeting work culture

tremendous.com

Post reply on HN
Print view View original

111–120 of 524 posts

Re: High-documentation, low-meeting work culture

#111

Post by simmschi »

gmd63 wrote: post #94
wpietri wrote: post #85

Earlier quoted context omitted.

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 behoo…

No, code actualizes the intent of the documentation and the product. The natural language description of a product shouldn't need to be discarded in lieu of some machine language. The lingua franca of ideas is natural language.

Fair enough, but you still end up with 2 separate ways to express things. And I have yet to see a company that changes the documentation first and then derives code changes from that.

Usually tickets are written, code is changed. Updating existing documentation is an afterthought at best.

Personally I prefer any formal or semi-formal documentation (e.g. Swagger) over a Confluence page any time of the day.

Re: High-documentation, low-meeting work culture

#112

Post by crazygringo »

ebiester wrote: post #30
canucklady wrote: post #20

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 would suggest introducing two things. First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.) Second, I would introduct the idea of a Documentation Portfo…

Diataxis looks fantastic. That chart on the home page is absolute gold.

Thanks so much for the link, I wish I'd had that chart ten years ago!

Re: High-documentation, low-meeting work culture

#113

Post by wpietri »

gmd63 wrote: post #94
wpietri wrote: post #85

Earlier quoted context omitted.

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 behoo…

No, code actualizes the intent of the documentation and the product. The natural language description of a product shouldn't need to be discarded in lieu of some machine language. The lingua franca of ideas is natural language.

I am familiar with the notion that programmers are people who turn documents into code. I just think it's rarely true and even more rarely necessary.

Personally, I don't think documents have intent. People have intent. Sometimes they write down some words as an approximate way to communicate their intent in that moment. But if there is a conflict between the written document and the actual intent, it's the human intent that matters.

I also think that drift between written description and actual intent is good and desirable, because it usually means that the humans learned something about what actually needs to happen. So to the extent that documentation acts as leg irons for intent, I'm generally opposed to it. The faster our teams learn, the better the things we make.

Re: High-documentation, low-meeting work culture

#114

Post by whatshisface »

layer8 wrote: post #54
tqi wrote: post #29

Earlier quoted context omitted.

Agree that hiring is sure important, but I think as long as hiring is competitive, and most candidates are bad at writing, then compromises are almost inevitable?

If FAANGs started putting more weight on technical-writing skills in their hiring, we would get Leetwriting and technical-writing bootcamps. Meaning, it’s just an education issue to some extent, and there’s currently too little motivation to train writing as a skill.

Leetcode doesn't raise people's IQs, it gives them practice effect on tech's favorite IQ test. So I don't think leetwriting would work for anything except getting practice effect on the new verbal IQ tests.

Re: High-documentation, low-meeting work culture

#115

Post by matwood »

Macha wrote: post #82
triceratops wrote: post #60

Earlier quoted context omitted.

> 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

Interesting. Not that long ago we moved everything out of Confluence into Google Drive because GD search worked. Confluence search was horrible to find docs I knew were there.

Re: High-documentation, low-meeting work culture

#116

Post by ip26 »

drewcoo wrote: post #37
giogadi wrote: post #22

Earlier quoted context omitted.

"Just write quality software" That's quite a load-bearing "just" there.

IMO, "quality" is going to be the sticking point.

No problem, we just need to hold a few meetings to define what counts as “quality”, and write it down in some good documentation.

Re: High-documentation, low-meeting work culture

#117

Post by wpietri »

simmschi wrote: post #111
gmd63 wrote: post #94

Earlier quoted context omitted.

No, code actualizes the intent of the documentation and the product. The natural language description of a product shouldn't need to be discarded in lieu of some machine language. The lingua franca of ideas is natural language.

Fair enough, but you still end up with 2 separate ways to express things. And I have yet to see a company that changes the documentation first and then derives code changes from that. Usually tickets are written, code is changed. Updating existing documentation is an afterthought at best. Personally I prefer any formal or semi-formal documentation (e.g. Swagger) over a Confluence page any time of the day.

Sure. But where some see the lack of updates as some sort of moral failure, I think it's usually a sign that there is a process problem. The documentation was supposed to solve some sort of problem, but the fact that people don't update it is usually a sign that either it wasn't a real problem, that documentation wasn't the right solution, or that there's a broken feedback loop in the team's process.

Re: High-documentation, low-meeting work culture

#118

Post by jasmer »

hinkley wrote: post #91
tqi wrote: post #12

Sounds like this works great for them, and an awesome environment to be a part of. However I'd be very curious to see how this evolves as the company grows. Personally, I am skeptical that this is sustainable in the long term. In my experience, most people are a) bad at writing and b) hate reading. And as a company grows, and the number of documents that need to be written and read explodes, this work pattern eventua…

People hate reading bad writing. As someone who dabbled in creative writing before discovering my vocation, I see a lot of problems caused by people not bothering to explain themselves clearly. As my time in the industry grew I begin to see people who were confused about their own ideas and came to see how many things we don’t even explain to ourselves. Which likely plays a role in how defensive people get about some…

It's shocking how many people don't have the ability to organize their thoughts.

I'm ashamed that I was completely guilty of this myself.

At some degree of professional development in software, you start to verbalize things, so as to 'explain them to yourself' and it helps clear things up.

This helped me understand that 'writing skills' (in this context) are frankly more matter of being able to organize concepts more than anything else.

A dev who can articulate is literally worth at least 50% more than one who cannot.

And to your point, yes, it's funny and scary when someone can't describe something they ought to be able to.

If someone can't explain something they are actually a risk to the code.

Re: High-documentation, low-meeting work culture

#119

Post by cmdrriker »

triceratops wrote: post #60
canucklady wrote: post #20

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.

Does it matter what tool you use to write documentation? Confluence gets a lot of sh*t because its in the grown-up camp of tools but I know people who've got problems even with nano.

It's incumbent upon all users or members of the team to use the common tool along with agreed upon standards. Otherwise even if you wrote documentation in your own hemoglobin, no one would touch it either.

Some manager prob chose _________ as the tool for ticketing, documentation, etc not because it was good at ______, or _______ but because it fulfilled their action plan to have something, anything in place so that if the universe goes supernova, well some stuff was written down.

In my journey it seems that nobody is willing to criticize Edward Teach for the lousy treasure map he left, but rather we make fun of those who're still looking for his stuff.

Re: High-documentation, low-meeting work culture

#120

Post by ip26 »

DenisM wrote: post #62
bluetomcat wrote: post #17

"High-documentation" isn't the cure, either. Just write quality software with well-defined interfaces, minimal dependencies and smooth building processes. I want to be able to build the thing without frustration, to start playing with it in order to learn its internals and debug it. Only then can I be comfortable enough to start implementing features and changes.

That’s how I often use documentation - start documenting something, then ask myself “should the code be fixed to avoid the need to document this part? Yes, yes it should”. A long provisioning instruction became much shorter as a result of automating it by reducing the need to document.

Are you pitching less documentation or none? It doesn’t seem like codebases are better when the architecture is unwritten.
Post reply on HN