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

231–240 of 524 posts

Re: High-documentation, low-meeting work culture

#231

Post by jcparkyn »

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.

> feel free to chime in

Pun intended?

Re: High-documentation, low-meeting work culture

#232

Post by celestialcheese »

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 Gitlab just really good at marketing their methodology as a tool to sell more subscriptions?

1 - https://about.gitlab.com/company/culture/all-remote/handbook...

Re: High-documentation, low-meeting work culture

#233

Post by rcarr »

goatlover wrote: post #210
rcarr wrote: post #183

Earlier quoted context omitted.

1. Paste image into assets folder. 2. Write ![imagename](imagename.jpg). It's not that hard really is it.

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.

Re: High-documentation, low-meeting work culture

#236

Post by lliamander »

ebiester wrote: post #30
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…

I would suggest introducing two things. First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.) Second, I would introduct the idea of a Documentation Portfo…

The diataxis seems quite interesting.

I see how it applies to documents which describe things as they are, but I'm curious how it would classify forward looking documents like technical designs, strategy and vision documents, roadmaps, and mission statements.

Re: High-documentation, low-meeting work culture

#237

Post by heydonovan »

beachy wrote: post #187
origin_path wrote: post #132

Earlier quoted context omitted.

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…

> To make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc. Maybe true in large orgs. But for smaller companies what I've seen is usually paralysis. e.g. someone notes a problem (maybe just a typo) in the doc. Can they fix it within seconds? If instead they need to raise a ticket then most likely it ain't happening.…

Disagree. A ticket should be created for any change, no matter how small. It takes seconds to write a title, body and hit submit. I've seen those small ad-hoc changes cause havoc because someone forgot to escape a single quote or didn't realize tabs were necessary and replaced them with spaces.

The default for Confluence is just that, everyone commits at will. There is no structure, tons of duplication, no standards when it comes to naming, formatting, audience, etc. I'm a huge fan of markdown/plain-text solutions, only because linters can be run that force you down one happy path. I don't believe Confluence has linters at all.

Re: High-documentation, low-meeting work culture

#238

Post by gautamdivgi »

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…

There are docs and then there are Docs. I think documents should be treated as source code. Go through a proper PR process so that you know what the latest and greatest is. Maintaining a wiki is one of the worst ways to document. It just creates a sprawl that is hard to control. I deal with it on a daily basis but have had little success with getting my team moving to our source control system for documents.

Re: High-documentation, low-meeting work culture

#239

Post by atom_arranger »

ramesh31 wrote: post #83
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…

This is why I find documentation to be either useless or actively detrimental. Your documentation is the code. Unless you have a dedicated technical writer on the team whose full time job is to work with developers to document their code, it all just becomes an outdated confusing mess immediately. Obviously this doesn't apply to public facing codebases. But trying to keep an internal codebase documented, other than f…

Agree. If possible the documentation should live in / be generated from the code as well.

I'm not checking confluence, write it in a ".md" file in the repo if you want me to see it.

Re: High-documentation, low-meeting work culture

#240

Post by znpy »

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…

We might be colleagues then.
Post reply on HN