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

491–500 of 524 posts

Re: High-documentation, low-meeting work culture

#491

Post by aiisjustanif »

mlazos wrote: post #19
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…

It works if you hire for people who are good at communicating and reward documentation writing in performance reviews

We already struggle finding people good at everything else lol

Re: High-documentation, low-meeting work culture

#492

Post by eastbound »

georgebarnett wrote: post #285
eastbound wrote: post #245

Earlier quoted context omitted.

“Stop, you were born with computers so you don’t notice it, but I’m not technical enough to paste an image in a Word document.” — The intern I just had to fire last month. She pretended because her generation was born with iPhones, that knowing advanced computer skills like Cmd+V was something that wasn’t a given at 21 years old. It blew my expectations about school - but at least school teaches them to find unexpect…

She grew up with computing systems that had no concept of keyboard shortcuts and intentionally abstracted away the concept of the file system and documents. I think her assessment of the situation is fair.

My assessment is that she can’t work in an office.

They can’t belong on the side of the world where we make things. She’ll forever belong in the people we’ve designed our apps for, viewing videos, playing games, instagram models, struggling to afford a flat. Maybe we’ll make her rich! Our apps will decide that.

Re: High-documentation, low-meeting work culture

#493

Post by Reitet00 »

mayas_ wrote: post #164
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'm a CTO in a startup and all our docs are in .md files, mermaid diagrams with dynamic Table of Content generation. We have two repos: Product (to anything relating to product) and Wiki (anything else, ranging from onboarding checklists, brief design documentation of key parts of the code ... to meta documentation) Although our team is small by many standards (8) everyone likes it. We spend a ridiculously small amou…

Thanks for sharing! Do you mind describing more technical details about the rendering pipeline for docs that you use?

Re: High-documentation, low-meeting work culture

#494

Post by arendtio »

satisfice wrote: post #371
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 will say the obvious: documentation sucks because good writing is a highly skilled activity that takes a lot of energy for most people to do, AND because keeping it up to date takes a lot of time, no matter how good you are at it, AND because leaders of companies don't want to spend ANY money on tech writers. That's it. No mystery. (BTW, this would also be why company financial records would suck, if management dec…

> good writing is a highly skilled activity

This. Yes, having everything written down and searchable is definitely a good goal. However, in my experience, the people in most companies have very different skills and few are good writers. So it probably takes a lot of time to create an organization that has a good process for creating great documents, let alone to transform an existing organization which can do so.

Re: High-documentation, low-meeting work culture

#495

Post by arendtio »

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.

So which tool do you like?

Re: High-documentation, low-meeting work culture

#496

Post by sidpatil »

k__ wrote: post #199
joegahona wrote: post #184

Earlier quoted context omitted.

Indeed, they look identical, even down to the font used.

Diataxis seems to be a fork of Divio. But according to the network graph on GitHub, Diataxis seems to be more active, although both of them still receive updates.

From the GitHub page, it looks like Divio is actually a fork of Diátaxis.

divio/diataxis-documentation-framework is forked from evildmp/diataxis-documentation-framework, and evildmp is Daniele Procida, the creator of the latter repository and the maintainer of diataxis.fr.

Re: High-documentation, low-meeting work culture

#497

Post by manv1 »

convolvatron wrote: post #261
manv1 wrote: post #34

All developers should spend time working in support. That time will make them appreciate the incredible power and utility that documentation provides to everyone...including your future self.

I find it to be really interesting for the first day or two...then I realize that our customers are often really terrible people using our product for really bad reasons and it undermines my whole faith in the project

Yeah, that's the downside to learning about end-users.

But it's better to know than to be ignorant, usually.

Re: High-documentation, low-meeting work culture

#498

Post by DocTomoe »

triceratops wrote: post #171
PragmaticPulp wrote: post #163

Earlier quoted context omitted.

You create the lowest friction/default path according to your company's needs. There isn't a universal note taking application that comes pre-organized for your team's use case. You have to put some work into any tool you use.

I disagree. The point of a tool is to reduce work. Most teams and companies aren't special snowflakes that need individualized organizations, and document hierarchies. There can be such a thing as sensible defaults that you customize or tweak later (no idea if Confluence ships with that - I've only ever seen Confluence installations in their already-screwed-up state). At the same time, an inexperienced user staring a…

Disclaimer: I am a consultant working for an Atlassian-centered consultancy. I do a lot of Confluence-based projects recently.

You would not believe how special some use-cases are, especially when you work with organisations that have highly regulated environments. I've seen anything from markdown files in a git repository being semiautomatically created in a Jenkins run to an organization having built essentially their own wiki software because nothing on the market fulfilled their need at the time (now 5 years later, they realise no-one uses that thing because it is just unintuitive). I have seen organisations that have no content oversight and some who had a whole department of "content czars", whose sole job it was to keep their documentation fresh and updated. I've seen organisations that had strict rules on approving each individual change, with complex approval workflows.

If you have never documented anything, Confluence may be overwhelming, but so will every tool that has "sensible defaults", because before too long, you will start hitting the envelope. Documentation software is not like a MacBook that you just buy and start using, you always need some level of customisation.

So, is Confluence damn good? No - there's a lot that could be improved. But from the mediocre solutions on the market today, it is one of the better choices.

Re: High-documentation, low-meeting work culture

#499

Post by DocTomoe »

origin_path wrote: post #452
_joel wrote: post #321

Earlier quoted context omitted.

Well there is (ftr I dislike confluence, but come on) https://marketplace.atlassian.com/apps/1216387/approvals-for...

Interesting but is it really used? Less than 1000 installs for a product as popular as Confluence?

Most use Comala: https://marketplace.atlassian.com/apps/142/comala-document-m...

Re: High-documentation, low-meeting work culture

#500

Post by DocTomoe »

SgtBastard wrote: post #242
matwood wrote: post #115

Earlier quoted context omitted.

Interesting. Not that long ago we moved everything out of Confluence into Google Drive because GD search worked. Confluence search was horrible to find docs I knew were there.

Confluence’s search is so bad, it might as well be a Write Once, Read Never tool.

That's because no-one bothers to read the documentation linked in the search field.

Protip: Use wildcards extensively. Differently from Google, Confluence search considers keywords entered to be limited by word delimiters. so foo matches only foo, not barfoo or footer. Use them with some wildcards, foo, and the search results starts to make sense.

Post reply on HN