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

151–160 of 524 posts

Re: High-documentation, low-meeting work culture

#151

Post by edgyquant »

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

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

Re: High-documentation, low-meeting work culture

#152

Post by triceratops »

EFreethought wrote: post #107
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.

> The only use case for Confluence is when you want to hide information, but credibly claim that it's documented. That describes Sharepoint more than Confluence.

Sharepoint is what you settle for when you can't convince your company to spring for Confluence.

Re: High-documentation, low-meeting work culture

#153

Post by jbverschoor »

j7ake wrote: post #145
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.

Well, you can actually just script that. Dropbox is fun, until you want previous versions.

At the place I worked for 22 years ago, we had an SMB fileshare for designers/front-end devs (html templates + templating lang), which would simply commit everything to CVS at night.

Re: High-documentation, low-meeting work culture

#154

Post by triceratops »

PragmaticPulp wrote: post #97
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.

Confluence (and all of the similar products) can be used successfully, but you need the teams to agree on and enforce a logical document hierarchy. It’s not really difficult to organize a company wiki into teams, projects, and other logical divisions if you make it a priority. The primary failure mode I see is when people just throw random documents into Confluence wherever convenient at time of writing and never go…

If using the lowest friction or default path in a tool leads to bad outcomes, that's a problem with the tool. Not the user.

Re: High-documentation, low-meeting work culture

#155

Post by rcarr »

tryauuum wrote: post #147
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..

For starters, the Confluence editor is absolutely dire. We can all stand here and sing til the cows come home about how it shouldn't be the world we live in, but the reality is that not a lot of people want to or have the time to write documentation so we should be making it as easy and fast as possible to do. As much friction as possible should be removed. It does not get a hell of a lot easier or quicker than writing a Markdown file.

Second, because it is plain text, search is blisteringly fast using any number of different tools. Following on from that for a third benefit: portability. You're not tied to any one service. You can use any text editor for editing and you can use a multitude of different solutions for publishing. Version control? Use whatever you what.

Another benefit: easy linking of files using [[wikilinks]] and block inclusion. If this is done properly, you can also use the graph view to get an oversight on how your code affects other parts of the codebase at a glance.

Re: High-documentation, low-meeting work culture

#156

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

#157

Post by triceratops »

SAI_Peregrinus wrote: post #146
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.

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

So simple an idea, it makes you wonder why it's not already a core feature in Confluence.

Re: High-documentation, low-meeting work culture

#158

Post by PragmaticPulp »

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 know git can be tricky but it cannot be that difficult to teach people from non technical departments

This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow.

If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all.

Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people.

Re: High-documentation, low-meeting work culture

#159

Post by rcarr »

waboremo wrote: post #140
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…

An easier one stop shop alternative is just Notion. Recommend it for the reason of having an internal wiki/documentation. Probably one of the only real use cases for Notion, everything else (like personal note taking or time organization) is horrible on it.

This was actually my next suggestion when Obsidian got shot down. It's definitely a nice half way house between the two. Again it got dismissed albeit this time with no explanation, I assume because the request for feedback and suggestions wasn't actually anything of the sort but basically a pretend exercise on behalf of management to 'show we're listening'.

Re: High-documentation, low-meeting work culture

#160

Post by koonsolo »

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 is indeed too technical. Try to explain how inserting an image is not just copy paste.
Post reply on HN