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

411–420 of 524 posts

Re: High-documentation, low-meeting work culture

#411

Post by bloaf »

CrypticShift wrote: post #292
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…

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…

You need to

1) Link to the documentation in your tools

2) Ensure everyone has edit access to the linked documents

Re: High-documentation, low-meeting work culture

#413

Post by balaji1 »

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.

Did I miss it or does the article specify what tools Tremendous uses for their documentation?

Re: High-documentation, low-meeting work culture

#414

Post by edgyquant »

justin_oaks wrote: post #251
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…

Unless the documentation enforcer has power, they'll just be an annoying voice. I don't care what that documentation enforcer has to say if my boss prioritizes code over documentation. You'd need management buy-in at every level for a high-documentation culture/company to work.

The same is true for testing though. Lots of shops write as few tests as possible, if any, because the devs don’t have to so they think their way is just fine.

I went from working as the annoying guy asking for tests and docs to the manager and we saw a huge improvement in performance, feature release and a reduction in bugs hitting prod. I can attest their way does not work just fine.

Re: High-documentation, low-meeting work culture

#415

Post by pxc »

phailhaus wrote: post #403
pxc wrote: post #339

Earlier quoted context omitted.

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.

You don't need WYSIWYG for dragging and dropping images into a document, or even for resizing them. WYSIWYG is an approach to layout and formatting, not the only alternative to writing LaTeX in a terminal-bound text editor.

Re: High-documentation, low-meeting work culture

#417

Post by apatters »

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…

So update the documents?

I mean, you're clearly not describing a high documentation culture, you're describing a culture that underinvests in intra-organizational communication.

I run a high documentation, low meeting culture by necessity (we operate in five time zones around world). Meetings vs docs is remarkably similar to the decision between paying for office space vs paying for occasional team retreats. If you run a fully remote company retreats are almost always a better use of your money than leasing office space. But you still need to pay for something.

Similarly with meetings vs. process documentation. If you're heavily remote and spread out I'd say you should cut down on meetings and being high documentation is the better choice. But again you still need to "pay" for something - you save time on meetings but you need to reinvest at least part of that time into writing documents.

Another bonus of documents is that they scale better than meetings. McDonald's doesn't deliver the same big Mac in every corner of the world by holding a lot of meetings. They have a book that goes out to all of their thousands of franchisees. When they want to add another thousand franchisees, they print more books.

If the documents are out of date my answer to my team is always "update them!" Anywhere that we're writing documents there are revision and discussion features so it's not like you can irrevocably screw something up, just improve it and let us know what you did. I do struggle with getting people to actually do it though.

Re: High-documentation, low-meeting work culture

#418

Post by spencerchubb »

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.

'bullied and cajoled' is an interesting set of verbs to use here. Is there a reason not to use metadata? Doesn't it make the web easier to index, and therefore easier for everyone to use?

Re: High-documentation, low-meeting work culture

#419

Post by password4321 »

password4321 wrote: post #335

Is there any documentation system that incorporates an expiration date, forcing manual review to renew? I also am interested in ways to tie source code and documentation together. For example: linking to methods in a way that follows refactoring.

lol - (re: linking) ask and ye shall receive!

Show HN: CodeLink: create links to blocks of code in your IDE

https://news.ycombinator.com/item?id=33711480

Re: High-documentation, low-meeting work culture

#420

Post by ch4s3 »

nichochar wrote: post #366

Moving to America from France, one of my biggest surprises was how poor the average engineer (person really, but engineers affect me directly at work) is at summarizing concepts clearly. I learned a little later that "summary" exercises are not a thing taught in school here, which surprised me. In France, "le résumé" is an exercise that they constantly drill into students (particularly technical ones), in which you t…

I had to do this for an undergraduate business degree here in the US and it feels like a super power working in software.
Post reply on HN