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

141–150 of 524 posts

Re: High-documentation, low-meeting work culture

#141

Post by icelancer »

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…

That just sounds like rebuilding Notion internally, and this is coming from someone who uses Obsidian locally and Notion company-wide.

Re: High-documentation, low-meeting work culture

#142

Post by dehrmann »

cateblanchett wrote: post #15
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…

doesn't Amazon have a similar structure, tho? i don't know what it's actually like to work there (anyone who does feel free to chime in) but i've interviewed and from what I can tell they put a heavy emphasis on documentation. it's tough to find a bigger and more siloed company than Amazon, and it seems to work for them.

They need high documentation to support their employee churn.

Re: High-documentation, low-meeting work culture

#143

Post by [deleted] »

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…

[deleted]

Re: High-documentation, low-meeting work culture

#144

Post by edgyquant »

fsociety wrote: post #136
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.

Ha I hear this a lot but the alternatives I have seen used are frankly just as terrible. I much prefer Confluence to a hidden web of Google docs.

For my team we’ve switched to using GitHub markdown files with flowcharts: located within the folder containing the subsystem it describes.

Re: High-documentation, low-meeting work culture

#145

Post by j7ake »

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 find Dropbox to have much less friction (almost zero) compared to git. In the teams with nontechnical people it is often enough to just use Dropbox. Git requires manually committing, which is friction and people often forget to commit changes.

The fact you need one person technical enough to resolve conflicts is already a deal breaker.

Re: High-documentation, low-meeting work culture

#146

Post by SAI_Peregrinus »

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.

We use Mark[1] to automatically create Confluence pages from Markdown documents in our git repos. So we can have a review process for documentation changes, the documentation of the code can be in the repo with the code, and yet it can still be accessed without having to give permissions to view the code repo! Helpful with a proprietary monorepo.

[1] https://github.com/kovetskiy/mark

Re: High-documentation, low-meeting work culture

#147

Post by tryauuum »

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…

confluence is ok, though I think I had problems with literal search: https://jira.atlassian.com/browse/CONFCLOUD-69222

What's the benefit of your solution? I mean git has excellent history lookup capabilities, but that's the only benefit I see. Maybe another one is that you can update documents without leaving cli..

Re: High-documentation, low-meeting work culture

#148

Post by tryauuum »

icelancer wrote: post #141
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…

That just sounds like rebuilding Notion internally, and this is coming from someone who uses Obsidian locally and Notion company-wide.

notion lost appeal when I noticed that search doesn't work. E.g. I have a page with wireguard mentioned in text and I cannot find it when searching for wireguard.

Re: High-documentation, low-meeting work culture

#149

Post by triceratops »

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

Oh yeah it's not great either I agree. But the use case for Google Docs is somewhat different in my mind. It's good for collaboration and discussion, rather than a source of truth to describe "how things are right now". It's annoying if you can't find a particular document immediately but it's not the end of the world. Discussion on a Google Doc will happen for a few weeks or a quarter, then die down and the doc will seldom be looked at again. You might link to it from tricky parts of your codebase but it's not essential to a high-level understanding.

Confluence and other wiki systems are clearly meant for longer-lived documentation and canonical information. You should link from or attach your working documents (spreadsheets, slide decks etc) to your wiki documentation for people to discover why certain decisions were taken. But if the wiki's discoverability is poor or it's not well-maintained or regularly reviewed, it's basically useless.

Re: High-documentation, low-meeting work culture

#150

Post by civilized »

fsociety wrote: post #136
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.

Ha I hear this a lot but the alternatives I have seen used are frankly just as terrible. I much prefer Confluence to a hidden web of Google docs.

Google Drive, the ultimate information black hole. Anything that gets sufficiently close will be sucked in and never seen again.
Post reply on HN