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

181–190 of 524 posts

Re: High-documentation, low-meeting work culture

#181

Post by joegahona »

PragmaticPulp wrote: post #158
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. Writin…

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

How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?

Re: High-documentation, low-meeting work culture

#182

Post by civilized »

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…

From my perspective, calling yourself a "high documentation" org leaves a similar impression as calling yourself a "high code" org.

Re: High-documentation, low-meeting work culture

#183

Post by rcarr »

koonsolo wrote: post #160
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.

1. Paste image into assets folder.

2. Write ![imagename](imagename.jpg).

It's not that hard really is it.

Re: High-documentation, low-meeting work culture

#184

Post by joegahona »

FooBarWidget wrote: post #138
ebiester wrote: post #30

Earlier quoted context omitted.

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…

What's the difference between Diataxis and the Divio documentation framework? https://documentation.divio.com/

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

Re: High-documentation, low-meeting work culture

#185

Post by vasco »

joegahona wrote: post #181
PragmaticPulp wrote: post #158

Earlier quoted context omitted.

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

> Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people. How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?

Most of the issues with Confluence I've seen are lack of organisation, out of date information mixed with up to date pages and really poor search / discoverability. The fact that people can just edit or create a page at any point is one of the better parts because it's easy for someone to fix something up during onboarding, during a drive-by consultation etc.

Re: High-documentation, low-meeting work culture

#186

Post by tgsovlerkhgsel »

koonsolo wrote: post #160
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.

Make it copy-paste. Automatically upload it to the image blob storage and insert the image code, then show the WYSIWYG preview.

Re: High-documentation, low-meeting work culture

#187

Post by beachy »

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…

> 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. They move on, and the next person experiences the same problem.

IMO the default should indeed be towards everyone committing at will. Yes that will result in the occasional snafu. Fix that when it happens. (obviously not good practice for the operating manual for a nuclear power plant - but for a <500 person Saas company it is).

Re: High-documentation, low-meeting work culture

#188

Post by otikik »

joegahona wrote: post #181
PragmaticPulp wrote: post #158

Earlier quoted context omitted.

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

> Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people. How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?

Google Docs

Re: High-documentation, low-meeting work culture

#190

Post by KaoruAoiShiho »

holoduke wrote: post #189

Documentation is worse than code. It's often outdated, difficult to understand and full of useless information. In every company I have been people hate to read docs and nobody wants to maintain them. I am not sure what a good alternative might be.

It just needs to be better than meetings to be well, better than meetings. Nothing is worse than meetings.
Post reply on HN