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

431–440 of 524 posts

Re: High-documentation, low-meeting work culture

#431

Post by SilasX »

stevesimmons wrote: post #340
Viliam1234 wrote: post #324

Earlier quoted context omitted.

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.

> But a different question is, why is no company trying to do this differently? I once worked at a company - in a different domain - that made a conscious decision to make this kind of hire. It worked incredibly well, and I never understood why more companies didn't do it. The context in my case was the Australian offices of a management consulting firm (BCG). The Melbourne and Sydney offices hired what were called "…

I would love that job, I'm always going back to presentations and finding better ways they could have made the point and identifying missing context what they would need to be more relevant.

Re: High-documentation, low-meeting work culture

#432

Post by hannasm »

twobitshifter wrote: post #48
oxff wrote: post #11

What about the low doc, low meeting culture

What is an example of that working? Just code that speaks for itself? How would you ever know why something was done?

I have had good experiences using commit messages for documenting the reasoning behind code changes.

Re: High-documentation, low-meeting work culture

#433

Post by Ginger-Pickles »

> We deliberately encourage people to create documents rather than build slide decks. Slide decks can mask poorly-written content with decorative font, sleek formatting, and compelling images.

>In a document, the content is all you have. It forces people to focus on communicating their ideas as clearly as possible.

Re: High-documentation, low-meeting work culture

#434

Post by eisa01 »

splittingTimes wrote: post #426

Is there any way to achieve this within Microsoft's suite? Sadly we adopted Microsoft O365, SharePoint, Teams. How can you organize the org effectively is beyond me, how does MS do it? Are they actually using their own tools they sell others? In our org, some departments/teams/sites have just a SP, Others have a teamspace with separate SP/document store. Worse, any meaningful file structure/hierarchy you come up with…

We use a shared OneNote, team of 20-50

Easy to use, desktop app, search, and crucially highlights new changes and additions so you can see something is updated

Re: High-documentation, low-meeting work culture

#435

Post by mrmrcoleman »

mr_gibbins wrote: post #128
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…

I'm sure these are great technological answers but this problem can be solved simply and quickly by a human. Not every issue needs to be solved by a butter robot. Why not employ a technical writer/documenter/whatever job title you like, even as a temp, whose sole job is to sort out the mess of documentation you have and then to write new documentation as you move forward?

I came here for the butter robot.

Re: High-documentation, low-meeting work culture

#436

Post by rkagerer »

If anyone who works there is reading this: There must be a spectrum of documentation-generating talent on staff. Have you ever had to read through the product of someone who isn't very good at writing it? How do you cope with mediocrity in that skill? (Is it sometimes cause to let someone go?)

Re: High-documentation, low-meeting work culture

#437

Post by bratbag »

vasco wrote: post #185
joegahona wrote: post #181

Earlier quoted context omitted.

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

Even poor discoverability can be fixed with labels.

But yes, the out of date info is a killer.

Re: High-documentation, low-meeting work culture

#438

Post by leghifla »

origin_path wrote: post #93
closeparen wrote: post #78

Earlier quoted context omitted.

Most people are a) bad at listening and b) hate meetings, but that doesn't stop them...

No not to the same extent. Meetings proliferate because people love them. LOVE them. Programmers dislike them because of flow but everyone else can't get enough of them. I only realized after enough years outside the tech industry. Meetings are like eating junk food. They make people feel important and like they had a busy/productive day, even if the actual mental effort required was low and the measurable output min…

About mental effort in meetings being lower than solving a technical issue, it is definitively true (most of the time), even though non-technical people cannot even grasp how much a difference there is.

In a previous software job, I was participating in a trade show. It was meeting after meeting, with both sales and technical aspects (I was paired with a sales guy). After several days like this, I remember vividly the sales guy saying how this trade show was good, but at the same time complaining how tired he was because all of these meetings. I kept it to myself, but for me, this was nearly like vacations compared to the day to day usual work

Re: High-documentation, low-meeting work culture

#439

Post by therealdrag0 »

throwawaaarrgh wrote: post #288
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…

Does using Git contribute anything of value to the documentation that you could not possibly get without git? The answer is, of course: no. You just want it because it's familiar to you. Which is fine... if you were the only person using it. Confluence is actually the best solution, hands down. It has a WYSIWYG. It supports Markdown. It has an API. It versions all content. It has fine-grained access control. It does…

I agree except I’ve been using Quip recently and it’s been a nice alternative to Confluence albeit similar.

Re: High-documentation, low-meeting work culture

#440

Post by peterbozso »

splittingTimes wrote: post #424
warrentr wrote: post #337

Earlier quoted context omitted.

This approach is definitely possible with a good web-based git IDE. We use gitlab's webIDE and have taught a few very non-technical (even temporary) employees how to do simple commits of markdown files (the trick here is high visibility into their commits -slack messages- and safeguards to make sure important things don't go live via CI too soon). There's a number of rough edges to sort out but this is vastly simpler…

I always marvel at gitlabs handbook and would love to introduce it to our company. Are there any tutorials how to set it up? (I don't mean how to set up gitlab, but rather which tools you need and how to set up the render pipeline, server etc to enable a markdown wiki/handbook?

GitLab employee here. This page of our handbook can be a good starting point to build your own: https://about.gitlab.com/company/culture/all-remote/handbook...
Post reply on HN