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

451–460 of 524 posts

Re: High-documentation, low-meeting work culture

#451

Post by SilverBirch »

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…

Yeah, having worked at a company who had to publish documentation, the technical writer was definitely an essential role. The engineer can write up the documentation, but you need someone external who can review, and interrogate what is written before it goes out. People are very poor at knowing what they need to communicate.

Re: High-documentation, low-meeting work culture

#452

Post by origin_path »

_joel wrote: post #321
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…

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?

Re: High-documentation, low-meeting work culture

#453

Post by Marta_B »

andfrob wrote: post #295
evolve2k wrote: post #243

Earlier quoted context omitted.

My sense is the markdown/git/render a documentation wiki with mkdocs is mostly solved. The issue is having that easy interface for non-tech folk. And related to this is the state of WYSIWYG markdown editing. The Basecamp folks created the very polished Trix rich-text drop-in which is a replacement for TinyMce, which while the standard seems to carry issues. Basecamp explained the issue with most approaches as such: >…

This would be worth checking out, which shows how CKEditor implements markdown editing: https://onlinemarkdowneditor.dev/

Yes, CKEditor accepts Markdown input thanks to a customizable autoformatting feature: https://ckeditor.com/docs/ckeditor5/latest/features/autoform... This allows users to employ all the familiar shortcodes on the go. It's basically the user's choice whether to type in Markdown or use the rich-text formatting buttons. Additionally, it's possible to switch the default CKEditor 5 output from HTML to Markdown: https://ckeditor.com/docs/ckeditor5/latest/features/markdown...

Re: High-documentation, low-meeting work culture

#454

Post by SilverBirch »

The problem with attempting a high-documentation culture is that it's very difficult to have a closed feedback loop. I see this all the time. Someone writes up "Here's what tool X does, and here's how to use it", and it never works. There's always some environment variable you forgot to set, or some local file, or some path that's literally /home/$USER/... in the code, or even worse "Here's the built binary, which isn't the same as the binary that gets built from source". How do you fix this? As part of your documentation process you get someone else to actually read and reproduce and review the document. And that person needs to be at arms distance to avoid shared knowledge being elided. To enforce this you also probably need it to gate atleast reasonably large PRs. You need ways to ensure the documentation doesn't go out of date. What am I saying? This only works in a process heavy environment. Which goes directly against what the author of this article says - which is a red flag. What can easily be the case here is you have 50 engineers all building new stuff, all writing reams of documentation which probably isn't at all useful, but because no one ever reads any of it, you never pay the cost...

Then you hire someone and for the first 6 months their life is hell until they clock on to what everyone else is doing and just ignore whatever everyone else is working on and plough their own furrow. Sure, we've now got 17 different poorly documented logging libraries (because no one wanted to invest in adopting anyone elses), but every individual developer is writing plenty of documentation! Oh and god forbid you disturb the author with questions outside of the 1 very short window for meetings in 1 specific time zone. Their careers page says "Join teammates from Hawaii to Brazil to Germany". Their meeting time is 6-9pm in Germany every day and 7am to 10am Hawaii time.

Re: High-documentation, low-meeting work culture

#455

Post by zppln »

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…

This sounds like a programmer's rather naive take to be honest.

Available PLM/PDMs could be improved a lot yes, but you're not gonna replace them by slapping a GUI on git (I mean, you could do that but it's really just a pretty small part of the problem space).

Re: High-documentation, low-meeting work culture

#456

Post by DoingIsLearning »

Viliam1234 wrote: post #324
ericmay wrote: post #135

Earlier quoted context omitted.

> Why not employ a technical writer/documenter/whatever job title you like Primarily because it's a far, far more complicated job than that and you can't really hire someone off the street to do it effectively. Typically in a tech company a tech writer is going to know almost as much or more (after years of experience diving into every detail) about a given technology or application or API, and so that begs the quest…

You explained why no one wants to take the job in the typical company. They would be disrespected, and likely soon fired. But a different question is, why is no company trying to do this differently? Like, hiring one good tech writer to maintain the company documentation, and paying them as much as they pay the developers.

Probably not the same pay as developers but the scenario you describe is already true in most regulated industries, where some regulated body actually asks for the docs on any given product.

Re: High-documentation, low-meeting work culture

#457

Post by iso1631 »

triceratops wrote: post #154
PragmaticPulp wrote: post #97

Earlier quoted context omitted.

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…

If using the lowest friction or default path in a tool leads to bad outcomes, that's a problem with the tool. Not the user.

The lowest friction is not doing any documentation

Re: High-documentation, low-meeting work culture

#458

Post by schnitzelstoat »

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.

Yeah, the search function in my company's confluence is abysmal.

There have been times I know a page exists and I even know the title/content of the page and yet still I am unable to find it via the search.

Re: High-documentation, low-meeting work culture

#459

Post by fool1987 »

jl6 wrote: post #14

High-Documentation is so out of fashion, for all the wrong reasons. If you are designing anything that is intended to last longer than 6 months, documentation is a critical part of the system. Meetings are great for communicating with people here and now, but only writing can communicate with people from the future. When you meet with your current colleagues, spare a thought for your future colleagues who haven’t yet…

Hard agree.

My current workplace culture (at least in the HW dept) is much more towards zero-documentation than anything I have experienced before and it has been a nightmare as a relatively new employee.

I waste so much time in reviews because I have done something non-standard despite having checked the standards docs but it turns out the standards have changed and no one bothered to update the docs. We don't even write specifications for products before we start work on them; if I make some architectural changes during the design, there is nowhere to record it. Drives me insane.

IMO there are two things that should be documented about any project: 1. The product itself: at least its interfaces, features and general architecture 2. The process of design: what changes were made vs the original spec, why, and when

If you want to know anything contained in that set of information here, you have to know who worked on the project so you can ask them about it, and then they have to be able to remember. It's not uncommon that changes are suggested and discussed multiple times within a project, or that changes are made but the reasons why are forgotten before the project is even complete.

I often joke that projects here are more "observed" than managed.

Exactly as you say - emails/meetings are ideal tools for discussion and decision making but for lasting records, you need documentation.

Re: High-documentation, low-meeting work culture

#460

Post by fool1987 »

justin_oaks wrote: post #247
jl6 wrote: post #14

High-Documentation is so out of fashion, for all the wrong reasons. If you are designing anything that is intended to last longer than 6 months, documentation is a critical part of the system. Meetings are great for communicating with people here and now, but only writing can communicate with people from the future. When you meet with your current colleagues, spare a thought for your future colleagues who haven’t yet…

This reminds me of when leadership announces a policy over email. Sure, all the people who got the email can follow it, but what about people who join the team in the future? Either they find out about the policy when they violate it and get reprimanded, or they hear about it via word of mouth. I've seen it a number of times in my career.

For sure! Why can't it be "we have updated/created X policy, please find it here: " ? Is that so much harder?

Most document management systems have a notification system built-in so that you can automatically email your all-staff mailing list when there is an update. It's very much a solved problem.

Post reply on HN