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

511–520 of 524 posts

Re: High-documentation, low-meeting work culture

#511

Post by scatterhead »

RugnirViking wrote: post #476
fool1987 wrote: post #463

Earlier quoted context omitted.

As the only person on my team who routinely documents my work (or at least who does so in a place visible to others), I definitely agree. I get very tired of people asking me things about my work where the reply is "it's in the docs, please check here: ." Makes me feel like a directory.

as someone who often would like to read documentation but have to end up asking the owner where it is like you describe My problem is that there are too many pages that may or may not be relevant/and/or up-to-date, I want to know if there is a better way? I can't just read every document the company has on the topic in vain hopes for the answer. For example, I recently started working on my company's mobile app - noo…

> I can't just read every document the company has on the topic in vain hopes for the answer.

If your documentation doesn't have a search feature, that's the first thing you need to fix.

If you're just bad at searching, well that's a very valuable and learnable skill.

> like setting up my dev environment

> the documentation which had been written both didn't include it (it was customer-facing

The user docs and the dev docs should be different corpses, searchable separately. What you describe sounds very disorganized.

Re: High-documentation, low-meeting work culture

#512

Post by lambdatronics »

thisisbrians wrote: post #7
ifloyd wrote: post #2

Our work culture's obsession with meetings, which is dwindling, it seems, is due in large part to our desire to perform as part of 'productivity theater.' this has mostly been driven up by wfh. but it's interesting to me that so many people focus on performativity vs. output

I think about this a lot. "Managers" are under pressure to make sure their teams are meeting goals/deadlines/whatever, so they are anxious, so they make efforts to observe and oversee "performance". Seeing people in meetings and diligently "working" makes them feel better about their teams' performance. But what really matters is outcome...which is very difficult to measure for a lot of software teams, and even harde…

https://dilbert.com/strip/1995-02-17

Re: High-documentation, low-meeting work culture

#513

Post by fool1987 »

scatterhead wrote: post #511
RugnirViking wrote: post #476

Earlier quoted context omitted.

as someone who often would like to read documentation but have to end up asking the owner where it is like you describe My problem is that there are too many pages that may or may not be relevant/and/or up-to-date, I want to know if there is a better way? I can't just read every document the company has on the topic in vain hopes for the answer. For example, I recently started working on my company's mobile app - noo…

> I can't just read every document the company has on the topic in vain hopes for the answer. If your documentation doesn't have a search feature, that's the first thing you need to fix. If you're just bad at searching, well that's a very valuable and learnable skill. > like setting up my dev environment > the documentation which had been written both didn't include it (it was customer-facing The user docs and the de…

There are two sides to the coin with not being able to find things - sometimes it is, as you say, because you are bad at searching for things, but sometimes things haven't been made in an easily searchable way. To name just three: - sections with ambiguous names; - multiple sections with the same name; or - information is split across separate sections/pages.

Worst case is that there is detailed documentation but it's all in the comments of twenty different Jira tickets.

I do agree that user docs and dev docs should be separated though, as should specifications and development logs.

Re: High-documentation, low-meeting work culture

#514

Post by fool1987 »

RugnirViking wrote: post #476
fool1987 wrote: post #463

Earlier quoted context omitted.

As the only person on my team who routinely documents my work (or at least who does so in a place visible to others), I definitely agree. I get very tired of people asking me things about my work where the reply is "it's in the docs, please check here: ." Makes me feel like a directory.

as someone who often would like to read documentation but have to end up asking the owner where it is like you describe My problem is that there are too many pages that may or may not be relevant/and/or up-to-date, I want to know if there is a better way? I can't just read every document the company has on the topic in vain hopes for the answer. For example, I recently started working on my company's mobile app - noo…

> I guess the only answer, as some others have mentioned, is a predictable organization system for the documentation, which crucially is actually taught to newcomers.

Precisely - just as you'd on-board new hires with information about codes of practise for development (code styles, nuances of internal git practice, etc.) you ought to at least have a "Contribution Guidelines" or similar doc that sets out how to structure and record information in the docs.

Re: High-documentation, low-meeting work culture

#515

Post by origin_path »

carom wrote: post #508
origin_path wrote: post #450

Earlier quoted context omitted.

Probably not IMO, it's very unlikely your source tree is structured the same way good docs should be. Docs are often task oriented, code is usually component oriented.

Ha, my tasks are usually updating those components. Mostly interested in developer efficacy. It is a real pain to find and reverse engineer components when starting a new gig. Would be nice to have an explanation and links to other components they interact with.

Sure. I tend to prefer a docsite generated using a rendering tool because when the docs look and feel high quality/high effort, people take it more seriously. But it can be that a README file in a set of directories is OK too. Chrome does this for example.

Re: High-documentation, low-meeting work culture

#516

Post by midoridensha »

spencerchubb wrote: post #418
beckingz wrote: post #316

Earlier quoted context omitted.

AI can't solve search. If you look at how google did it, they bullied and cajoled site owners to add detailed metadata to the top of pages. It's not magic, it's creating incentives for people to create documentation.

'bullied and cajoled' is an interesting set of verbs to use here. Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?

>Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?

Yes, there's a very good reason not to use metadata: it's extra work, and it's not very fun, just like writing docs for software. So people don't want to do it because it isn't "sexy" (and there aren't very good incentives to overcome people's reluctance to do that work).

Because of this, just like any job that people don't really want to do, you have to "bully and cajole" them into doing it.

Re: High-documentation, low-meeting work culture

#517

Post by rcarr »

koonsolo wrote: post #446
rcarr wrote: post #208

Earlier quoted context omitted.

Well presumably this would be less of an issue if you had easy to use, easy to search and easy to maintain documentation, you know, maybe in the form of markdown files with a search bar where you could type 'how to paste image into documentation' in case you forgot... At the end of the day, if you've got someone who can't work out how to drag a file into a folder and then type ![imagename](imagename.jpg) after you've…

At the end of the day, if you've got someone that can't figure out there are people that are not good at technical things, do you really want them to develop your user facing software?

Ok mate we’ll all go back to living in huts because we decided we had to go at the pace of the slowest people in society.

Re: High-documentation, low-meeting work culture

#518

Post by icedchai »

origin_path wrote: post #127
tqi wrote: post #103

Earlier quoted context omitted.

I think that's a bit ungenerous to think that programmers are somehow different in this regard. Everyone hates attending boring meetings. And non-programmers also have heads down individual work they need to / would rather be doing. However I agree that the extent of it is the key. I think most people actually hate running meetings (it's basically public speaking), but they hate writing documents even more. It's much…

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…

I was in yet another meeting the other day, and we had more "observers" than actual contributors / workers. Totally absurd. At the end of the meeting, some of the "observers" simply don't understand the meeting, and want a follow up meeting to discuss the meeting, so they discuss it in yet another meeting (presumably to appear intelligent so even more meetings can be scheduled.)

I've also noticed the PowerPoint issue: densely packed slides look ridiculous and don't project well. I think a lot of people wind up simply reading off the slides.

Re: High-documentation, low-meeting work culture

#519

Post by euroderf »

CrypticShift wrote: post #292
ericmay wrote: post #135

Earlier quoted context omitted.

> Why not employ a technical writer/documenter/whatever job title you like Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the quest…

Summary: HIGH Documentation = HIGH staleness + HIGH loss. HIGH staleness is because nobody wants to do it (status is lower). Also… nobody else can do it (full understanding of what is being documented is needed) So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopel…

A feature of docs-as-code is having the (typ. markdown) docs live in the code directories. Leaving no excuses for tech people not to update them, or at least insert a TODO.

Another idea might be, whenever a new feature is closed out, auto-allocate some percentage of its implementation time to documentation, and schedule an interview with a tech writer.

Re: High-documentation, low-meeting work culture

#520

Post by euroderf »

baby wrote: post #373
ericmay wrote: post #135

Earlier quoted context omitted.

> Why not employ a technical writer/documenter/whatever job title you like Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the quest…

Usually a tech writer is also some sort of PM role that gets to chase developers and get them to explain what's in their head. Sometimes you have to have such a person on board.

Get the brain dump when it's all still fresh in the head !
Post reply on HN