High-documentation, low-meeting work culture • Hacker News Board

Re: High-documentation, low-meeting work culture

#381

Post by baby » Wed, Nov 23, 2022, 1:56 AM UTC

Xeoncross wrote: post #303

justin_oaks wrote: post #251

Earlier quoted context omitted.

Unless the documentation enforcer has power, they'll just be an annoying voice. I don't care what that documentation enforcer has to say if my boss prioritizes code over documentation. You'd need management buy-in at every level for a high-documentation culture/company to work.

Sure, replace documentation enforcer with security team. Same argument.

Exactly my thought, these people will burn out and there's just no way around that. Sometimes you need people whose job is to burn out trying to pull others in one direction

Re: High-documentation, low-meeting work culture

#382

Post by vonnik » Wed, Nov 23, 2022, 2:00 AM UTC

Nevermark wrote: post #374

vonnik wrote: post #360

I've worked at high-documentation companies and low-documentation companies. Documentation is hard to create and hard to maintain. It is essentially a simulation of an underlying reality, and that underlying reality *always* changes faster than the documentation can. So the documentation ends up being spotty, except for the parts that you find a way to automate. It's hard to automate all documentation, since so much…

This can be improved with two sets of links for each doc. A set of manually added links to previous related material, with optional note. New links can be added by anyone. And a set of automatically generated reverse links, to documents that referenced the one being viewed. Both kinds of links help create continuity and context.

Again, that a lot of extra work, and the automatic reverse links are v tooling dependent. You don't get them with Confluence or gDocs, fwiw.

Nor do these suggestions solve the problem of doc creation.

What many people ignore in these discussions is the real tradeoff between "time spent in meetings with people who can answer questions" vs "time spent by non-professional writers trying to be clear for strangers".

Re: High-documentation, low-meeting work culture

#383

Post by qwertygnu » Wed, Nov 23, 2022, 2:06 AM UTC

njarboe wrote: post #368

nichochar wrote: post #366

Moving to America from France, one of my biggest surprises was how poor the average engineer (person really, but engineers affect me directly at work) is at summarizing concepts clearly. I learned a little later that "summary" exercises are not a thing taught in school here, which surprised me. In France, "le résumé" is an exercise that they constantly drill into students (particularly technical ones), in which you t…

Teaching how to write summaries in the US would be a good idea. To make things even worse, in the US most essays are assigned a minimum length so students learn to pad their writing with lots of fluff and circumlocutions.

Purely anecdotal, but I recall plenty of summarizing assignments, along with other reading comprehension tasks in my English classes. Though you're right about the minimum length padding thing reinforcing the opposite skill.

Re: High-documentation, low-meeting work culture

#384

Post by Raidion » Wed, Nov 23, 2022, 2:06 AM UTC

danny_codes wrote: post #195

simmschi wrote: post #111

Earlier quoted context omitted.

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.

I think most of us approach documentation without intention. We write to express the idea, but fail to consider how the documentation fits into the deliverable. For example, one could structure things where the English documentation is the deliverable. The code merely serves to actualize the document. In this world, we would consider the act of writing documentation of paramout importance, whereas the code is an impl…

Code is more complex than documentation specifically because it needs to deal with every issue. If you're going to cover every edge case in documentation, just write the code. Tools like OpenAPI/Swagger blur the lines.

Documentation is useful when it's job is to help understand why the code is the way it is, what problems are trying to be solved, and what constraints the devs had.

Re: High-documentation, low-meeting work culture

#385

Post by edgyquant » Wed, Nov 23, 2022, 2:09 AM UTC

convolvatron wrote: post #252

edgyquant wrote: post #151

Earlier quoted context omitted.

Which is unacceptable for an engineer who must participate in architecture meetings.

does anyone do that anymore? for me this is the real failure and design documentation being shitty is just a symptom group design is a really important skill, and people don't even recognize that its a thing

Does anyone do what? Fail to pay attention/retain architecture via meeting? Because yeah engineers definitely tend keep working/browse Reddit during meetings because they feel they have better stuff to do.

Re: High-documentation, low-meeting work culture

#386

Post by andrewflnr » Wed, Nov 23, 2022, 2:11 AM UTC

mr_gibbins wrote: post #128

ebiester wrote: post #30

Earlier quoted context omitted.

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…

I'm sure these are great technological answers but this problem can be solved simply and quickly by a human. Not every issue needs to be solved by a butter robot. Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?

> I'm sure these are great technological answers

They're not, actually, as is obvious if you actually read the links. They're human process approaches.

Re: High-documentation, low-meeting work culture

#387

Post by closeparen » Wed, Nov 23, 2022, 2:16 AM UTC

tqi wrote: post #342

origin_path wrote: post #127

Earlier quoted context omitted.

Well people say they hate attending boring meetings, but when you observe what people do it's normally the coders who actively find ways to skip / who aren't setting up new meetings / are requesting fewer meetings. Other job roles, at least in my experience, tend to jump to a meeting as the first reaction. Developers will say: let's discuss it over email. Others say: let's hop on a call / grab a room. The number of m…

> you observe what people do it's normally the coders who actively find ways to skip / who aren't setting up new meetings / are requesting fewer meetings Interesting - I actually chalk up that to two things: first, people in SWE roles having historically been given a tremendous amount of latitude for behavior that does not conform to "professional" norms. The freedom to dress however they want, work from home, and sk…

I think the meetings people consider wasteful are not the ones with a lot of substantive content related to their work.

Re: High-documentation, low-meeting work culture

#388

Post by biztos » Wed, Nov 23, 2022, 2:21 AM UTC

FridgeSeal wrote: post #275

jrochkind1 wrote: post #264

Earlier quoted context omitted.

what's a butter robot? (I feel like i'm setting up a punchline for a joke somehow...)

It’s a reference to this: https://youtu.be/X7HmltUWXgs

Haha that’s awesome. I had figured it was just a typo for “better robot.”

Re: High-documentation, low-meeting work culture

#389

Post by xapata » Wed, Nov 23, 2022, 2:30 AM UTC

sib wrote: post #318

crazygringo wrote: post #283

Earlier quoted context omitted.

Yeah, I think you're "doing it wrong" as much as I hate to say that, sorry. Search is keyword-based, like large-scale search is pretty much anywhere. Expecting "specifications" to match "spec" is expecting too much, same as expecting half your search to match a folder and the other half to match a file the folder is in. The main thing to keep in mind is that search is content-based, not just filename. So instead, sea…

True, although this is Google we're talking about and Google [web] search is smart enough to do a lot of statistically-driven NLU-type things on top of pure keywords... (I currently work at Google, but not in Search or Drive / Docs...)

Google Photos search is magical.

Re: High-documentation, low-meeting work culture

#390

Post by pcurve » Wed, Nov 23, 2022, 2:41 AM UTC

nichochar wrote: post #366

Moving to America from France, one of my biggest surprises was how poor the average engineer (person really, but engineers affect me directly at work) is at summarizing concepts clearly. I learned a little later that "summary" exercises are not a thing taught in school here, which surprised me. In France, "le résumé" is an exercise that they constantly drill into students (particularly technical ones), in which you t…

It’s probably part cultural as well because We teach the opposite. We encourage students to be verbose. Longer term papers are rewarded. Your graduate thesis? How about 100 pages.

We also encourage bullshitting in everyday communications. It drives me nuts.