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

251–260 of 524 posts

Re: High-documentation, low-meeting work culture

#251

Post by justin_oaks »

Xeoncross wrote: post #139

If you have a high-documentation culture, you must have documentation enforcer roles. It's crazy to think you would have a library without librarians to run it. There must be people who sole role in the company is to spend time on each team (in sequence) trying to follow or review their docs and get X running "like the docs say" This group of enforcers will contain a variety of people from tech, legal, customer servi…

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.

Re: High-documentation, low-meeting work culture

#252

Post by convolvatron »

edgyquant wrote: post #151
closeparen wrote: post #78

Earlier quoted context omitted.

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.

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

Re: High-documentation, low-meeting work culture

#253

Post by peterbozso »

celestialcheese wrote: post #232

From the outside, Gitlab seems to have solved this with a medium-sized org with all remote, and it sounds like a dream remote workplace. Async communication, full transparency, 90-day retention in slack which forces decisions into documentation if it's important, issues/threads for discussions, and handbook for SOPs [1] Anyone have experience with this directly that can speak to if this works in practice? Or is Gitla…

GitLab employee here. Can confirm, it works exactly as advertised to the outside world.

Re: High-documentation, low-meeting work culture

#255

Post by howenterprisey »

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 use Confluence pretty heavily at work (I write most of our docs) and I like it. Any annoying UI elements, I hide with ublock origin. I don't mind the lag, although I do wish it were faster.

Re: High-documentation, low-meeting work culture

#256

Post by epolanski »

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…

> a) bad at writing and b) hate reading

Why does everyone else has to pay the insane price for that?

Re: High-documentation, low-meeting work culture

#258

Post by phailhaus »

rcarr wrote: post #233
goatlover wrote: post #210

Earlier quoted context omitted.

So you're replaced something that's simple as paste in office documents with two separate steps, one outside the app requiring the user to navigate to the assets folder, and the second requiring remembering specific syntax.

Not really because if you're using Obsidian you can just copy paste images and it will handle the syntax and moving the asset into the correct location anyway. But is taking an hour to read through a markdown cheatsheet really the worst thing in the world if what you end up with is far more useful and maintainable documentation? Seems like a pretty big pay off for not a lot of staff training.

> But is taking an hour to read through a markdown cheatsheet really the worst thing in the world if what you end up with is far more useful and maintainable documentation?

This makes no sense given that you get the same payoff by using something like Atlassian's wiki. No git, no markdown, none of this nonsense, users can just immediately hit the ground running with advanced formatting support and version history.

I think you're lacking a lot of empathy for nontechnical users. I don't see how you could ever argue that your git + Obsidian stack is "more valuable" than an off-the-shelf wiki solution.

Re: High-documentation, low-meeting work culture

#259

Post by pxc »

origin_path wrote: post #132
cmdrriker wrote: post #119

Earlier quoted context omitted.

Does it matter what tool you use to write documentation? Confluence gets a lot of sh*t because its in the grown-up camp of tools but I know people who've got problems even with nano. It's incumbent upon all users or members of the team to use the common tool along with agreed upon standards. Otherwise even if you wrote documentation in your own hemoglobin, no one would touch it either. Some manager prob chose _______…

It does matter because the issue with wikis (not just confluence) is there's no approval or review workflow. Imagine trying to write a large program in which everyone could just commit at will, with no review process whatsoever, and where nobody had made any decisions about design up front. There'd be duplication, dead code, the organization would be crazy. That's the average wiki. It's a commons and a tragic one. To…

There are some really nice git-based wiki systems out there, and one is built into GitHub and GitLab. If you want that type of workflow for your wiki, it's easy to get.

Re: High-documentation, low-meeting work culture

#260

Post by amendegree »

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…

You'd have a much easier time getting this adopted if you created a fancy GUI on top of the infra you just detailed out. Most people don't want to deal with git, no one wants to write in markdown all day, and the more obstacles you introduce to making documentation the less documentation gets made.

If the two options are confluence and sharepoint I choose confluence every time. Somehow people have decided that because sharepoint can do document store and html it's a kb. and because it comes with O365 exec's love it because its "free".

Post reply on HN