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

341–350 of 524 posts

Re: High-documentation, low-meeting work culture

#341

Post by kfrzcode »

kfrzcode wrote: post #215
rcarr wrote: post #134

I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departme…

I like Confluence! It serves it purposes and provides a lot of niceties, and is - as you mention - integrated with other Atlassian tooling. Nice ecosystem!

* its

Re: High-documentation, low-meeting work culture

#342

Post by tqi »

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…

> 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 skip out on meetings they don't want to attend are all of a piece. And second, I think software engineering work is often (generalizing as well) less cross functional than other roles. Gathering requirements and understanding how it fits into a larger company plan is usually tasked out to PMs or tech leads, which is not something I've seen for Finance, HR, Legal, or other functional roles. So the need to schedule their own meetings is also lessened.

Re: High-documentation, low-meeting work culture

#343

Post by brendank310 »

Viliam1234 wrote: post #324
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…

You explained why no one wants to take the job in the typical company. They would be disrespected, and likely soon fired. But a different question is, why is no company trying to do this differently? Like, hiring one good tech writer to maintain the company documentation, and paying them as much as they pay the developers.

A previous team I was on ended up with this role. Strong writer with no technical skills joined the team and worked hand-in-hand with engineers fleshing out docs. It was productive for the engineers because they needed to articulate the ideas very clearly. The writer has been attached to that project now for 6-7 years at this point, and could probably stand in as a support engineer for some problems. It was a little painful getting HR to approve a tech writer getting paid close to an engineer position (this was after a few years).

I do like the sibling comment calling for a librarian. I imagine that would pay a ton of dividends if the librarian was motivated and got support.

Re: High-documentation, low-meeting work culture

#344

Post by tqi »

rcarr wrote: post #134

I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departme…

I don't think documentation is a problem with a technical solution - it's an organizational commitment and incentives problem.

Re: High-documentation, low-meeting work culture

#345

Post by CrypticShift »

beckingz wrote: post #316
CrypticShift wrote: post #292

Earlier quoted context omitted.

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…

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.

First, I’m assuming the documentation is already updated (i.e., 1st part is OK = no staleness)

Second, the whole point of AI NLP search (i.e., 2nd part = loss) is that it does not need metadata (which was the basis of the now mostly abandoned semantic web approach to KM).

Re: High-documentation, low-meeting work culture

#346

Post by gopher_space »

ericmay wrote: post #135
mr_gibbins wrote: post #128

Earlier quoted context omitted.

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?

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

> 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.

Library science is a popular area of study but the job market isn’t great and neither is the pay. Lots of people to choose from here even without poaching from existing libraries.

Re: High-documentation, low-meeting work culture

#347

Post by tqi »

closeparen wrote: post #78
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…

Most people are a) bad at listening and b) hate meetings, but that doesn't stop them...

> Most people are a) bad at listening and b) hate meetings, but that doesn't stop them...

True, people are bad at both but I think many people view a 30 minute meeting where they can voice over an idea as a lower lift than sitting down and writing a well structured doc (see also: Loom). Plus, it's easier to enforce attendance than to enforce reading a document. So meetings are the path of least resistance.

Re: High-documentation, low-meeting work culture

#348

Post by sauravc »

I thought this was a well written article and I loved the graphics (especially the one about 30 minute meetings actually taking 68 minutes). However, it's worth noting that this company is fairly small (48 members according to their About page) and that the group has been together for quite some time.

I'm not sure how well this would scale past the Dunbar number, or for organizations growing rapidly.

Either way, I'm glad they published this.

Re: High-documentation, low-meeting work culture

#349

Post by mgbmtl »

loudmax wrote: post #179
rcarr wrote: post #134

I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departme…

This is what the Gitlab wiki does. There's a markdown+git interface for technical folks and a web interface for normal people.

It's what we use, and what I find the be the less annoying solution, but there are two big show-stoppers to make it more user-friendly:

- the default index on the sidebar doesn't handle sub-directories well (https://gitlab.com/gitlab-org/gitlab/-/issues/17673) - we use a pipeline to refresh an index page, but it's duct-tape and annoying to setup.

- can't edit only a section of a page, so if the page has a few sections, I often lose track of what exactly I wanted to change (maybe the WYSIWYG helps here, have to admit I have not used it much)

Otherwise I like that each project has its wiki, and so instead of one huge messy wiki, it's a few smaller messy wiki, easier to cleanup and have clear owners.

Re: High-documentation, low-meeting work culture

#350

Post by CrypticShift »

Viliam1234 wrote: post #324
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…

You explained why no one wants to take the job in the typical company. They would be disrespected, and likely soon fired. But a different question is, why is no company trying to do this differently? Like, hiring one good tech writer to maintain the company documentation, and paying them as much as they pay the developers.

> differently? Like, hiring one good tech writer to maintain the company documentation

He assumes that "full understanding (into every detail) of what is being documented is needed" (as I put it). So, the new hire will never get it right 100%. he will both struggle and annoy others (to forever enlighten him), which is a fair point.

But it is not black or white. Others here have more positive experiences

Post reply on HN