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

401–410 of 524 posts

Re: High-documentation, low-meeting work culture

#401

Post by mycall »

beckingz wrote: post #316
CrypticShift wrote: post #292

Earlier quoted context omitted.

Summary: HIGH Documentation = HIGH staleness + HIGH loss. HIGH staleness is because nobody wants to do it (status is lower). Also… nobody else can do it (full understanding of what is being documented is needed) So, to solve the first staleness part, there is only two ways: raise the documenter status, or make it somewhat possible (easier?) for someone else to do at least a part of it. are they both really that hopel…

AI can't solve search. If you look at how google did it, they bullied and cajoled site owners to add detailed metadata to the top of pages. It's not magic, it's creating incentives for people to create documentation.

The better question to ask is if AI can do the ghost writing that high-documentation culture needs. This is an interesting hypothesis for GPT-4

Re: High-documentation, low-meeting work culture

#402

Post by phailhaus »

albedoa wrote: post #379
phailhaus wrote: post #336

Earlier quoted context omitted.

What issues do nontechnical people have with Confluence that are easier in just Markdown? The typical gripes are around search and organization , not editing. Markdown would be seen as a massive downgrade in experience.

> What issues do nontechnical people have with Confluence that are easier in just Markdown? Your claim that I was responding to is that "everything Just Works" in Confluence, not that Markdown is easier. I have commented on neither Markdown nor their relative ease. > The typical gripes are around search and organization , not editing. That would seem to contradict both that everything Just Works and that you have nev…

> I have commented on neither Markdown nor their relative ease.

Unfortunately, you've inserted yourself into a conversation where this is what we're talking about. If you want to talk about something else, maybe start your own thread.

The point of contention here is that Atlassian's wiki is far easier for nontechnical people to deal with than pure markdown and git. And yes, from their perspective, it Just Works. They never wrangle with syntax, there's a massive plugin ecosystem for custom features, and version history works out of the box.

Re: High-documentation, low-meeting work culture

#403

Post by phailhaus »

pxc wrote: post #339
phailhaus wrote: post #334

Earlier quoted context omitted.

> If you want technical documentation that developers are going to maintain, it has to be a joy to work with in their own editors. Not what we're talking about here though, OP is suggesting it's reasonable to teach business analysts markdown and git for all company documentation.

It's unlikely that they'll actually use Git, but teaching them Markdown is absolutely doable. And any modern Git forge will let you edit a Git-based wiki in the web UI without knowing what a commit is.

"I want to insert an image." Whoops, you're already in deep trouble. "I want to resize it." Even worse!

These are table stakes features that everyone expects to work out of the box. If you don't give them a WSIWYG editor that does all of this for you automatically, it's DOA.

Re: High-documentation, low-meeting work culture

#404

Post by wankle »

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…

Agreed, we use Confluence and use an agreed upon structure. It works fine from what I've experienced.

Re: High-documentation, low-meeting work culture

#405

Post by jumpei163 »

sdflhasjd wrote: post #89
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…

It's actually hilarious how Google - a company famous for it's search engine - made Docs, who's search function cannot find anything.

Are you using search feature in Drive? I've been using CloudSearch, which I heavily rely upon

Re: High-documentation, low-meeting work culture

#406

Post by tshaddox »

hw wrote: post #396
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…

What many dont realize is that documentation is tech debt. You can spend a lot of time and write a lot of documentation and have to also spend time updating it. I have worked with teams that focus so much time on design docs and insist that everything has to be documented. Pace of work is slow. Documentation and designs became obsolete due to shutting down of services, change in architecture, refactors. The best form…

I think it’s a bit odd to call it tech debt. I’d say something more like “documentation is part of your tech, and needs to be maintained like the rest of your tech.” It’s only tech debt if you decide to not maintain it.

Re: High-documentation, low-meeting work culture

#407

Post by wankle »

triceratops wrote: post #244
beachy wrote: post #187

Earlier quoted context omitted.

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

Ticket, or pull request? Mandating a Jira ticket for simple typo fixes is overkill. But if you make it easy to create a PR directly on the documentation file, without leaving the tab, I don't see an issue. This is already a Github feature.

We did PR's on documentation files at my last place, it worked but it was more painful than getting reviews for code PR's. Tickets work because they can be reasoned about, shoved aside, brought back into the limelight, updated, other tickets can easily be related to them as more information is discovered, etc.

Overall the comments on this page fall into 2 camps, people who've tried it all and found what works is discipline and those who are still trying it all.

Re: High-documentation, low-meeting work culture

#408

Post by albedoa »

phailhaus wrote: post #402
albedoa wrote: post #379

Earlier quoted context omitted.

> What issues do nontechnical people have with Confluence that are easier in just Markdown? Your claim that I was responding to is that "everything Just Works" in Confluence, not that Markdown is easier. I have commented on neither Markdown nor their relative ease. > The typical gripes are around search and organization , not editing. That would seem to contradict both that everything Just Works and that you have nev…

> I have commented on neither Markdown nor their relative ease. Unfortunately, you've inserted yourself into a conversation where this is what we're talking about. If you want to talk about something else, maybe start your own thread. The point of contention here is that Atlassian's wiki is far easier for nontechnical people to deal with than pure markdown and git. And yes, from their perspective, it Just Works. They…

> this is what we're talking about.

You have lost your own plot then. This is not about Markdown:

> I have never heard nontechnical people complain about the Confluence wiki. From their perspective, everything Just Works.

Re: High-documentation, low-meeting work culture

#409

Post by wankle »

Viliam1234 wrote: post #325
lukewiwa wrote: post #315

Earlier quoted context omitted.

The last thing I want is to raise the friction for writing down documentation. It's hard enough to get technical minded people to contribute to a git (or style) based knowledge base. Pick your poison I guess but I'm quite happy to have testers/BAs/directors/etc able to quickly jot down thoughts roughly than have it disappear into the ether.

> The last thing I want is to raise the friction for writing down documentation. A better solution might be that anyone can write the documentation, and there is a maintainer who constantly refactors the wiki to keep it legible. Makes sure the information is not duplicated, adds hyperlinks to things, etc.

Internal documentation is everyone's responsibility, not a "tech writer". External should be written by a professional, agree.

Re: High-documentation, low-meeting work culture

#410

Post by jollofricepeas »

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…

Exactly this.

I think that high documentation can work BUT the company has to invest in it in the way that Digital Ocean or even Stripe has done outwardly.

1. Investment - You have to hire at least a few technical writers and librarians to provide training & cleanup functions.

2. Management buy-in - You have to budget for it and encourage it through day one communication (ie. New hire training) and consistently rewarding and recognizing people for getting it right.

Post reply on HN