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

471–480 of 524 posts

Re: High-documentation, low-meeting work culture

#471

Post by chrisrickard »

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…

Yes!!

Agile taught us working software over comprehensive documentation, but it also made huge generation of people thinking that all documentation was bad, and not just "comprehensive" (or "overblown").

Documentation (words) is how many complex concepts are communicated.

I've built a requirements management system to handle this (https://userdoc.fyi), and it's made many projects I've worked on 200% easier for developers, project managers, and all stockholders.

I think high-Documentation is out of fashion as a reaction to agile, but things are swinging back the other way.

Re: High-documentation, low-meeting work culture

#472

Post by ebiester »

q7xvh97o2pDhNrh wrote: post #378
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…

Whoa! I love a good 2x2, and the one on the Diataxis home page is great ! Adding a caption here for anyone on a screen-reader, before I give commentary on it: * X-axis: "serve our study" vs "serve our work" * Y-axis: "practical steps" vs "theoretical knowledge" * which gives 4 quadrants: how-to guides, tutorials, explanation, and reference So I'm joining a new place recently, and it's another one of those "documentat…

Almost every developer I've ever seen defaults to "explanation." Reference is there to the extent that it can be auto-generated, but most companies are relatively light on reference. Tutorials are pretty rare in smaller orgs - it rarely gets prioritized.

How-tos are an interesting case. I see a lot of informal how-tos in slack. However, how-tos also are the most likely to become stale because if they're needed often enough, they tend to become automated in part or whole. It is by its very nature transitory.

Re: High-documentation, low-meeting work culture

#473

Post by thepawn1 »

spencerchubb wrote: post #418
beckingz wrote: post #316

Earlier quoted context omitted.

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?

The age old issue. There's oodles of data at how people don't keep doing it because it's toil to them.

Re: High-documentation, low-meeting work culture

#474

Post by [deleted] »

unnah wrote: post #443
crazygringo wrote: post #283

Earlier quoted context omitted.

Yeah, I think you're "doing it wrong" as much as I hate to say that, sorry. Search is keyword-based, like large-scale search is pretty much anywhere. Expecting "specifications" to match "spec" is expecting too much, same as expecting half your search to match a folder and the other half to match a file the folder is in. The main thing to keep in mind is that search is content-based, not just filename. So instead, sea…

So basically you have to search google docs like you used to search the web before google came along and revolutionized search?

[deleted]

Re: High-documentation, low-meeting work culture

#475

Post by alohaandmahalo »

peterbozso wrote: post #253
celestialcheese wrote: post #232

From the outside, Gitlab seems to have solved this with a medium-sized org with all remote, and it sounds like a dream remote workplace. Async communication, full transparency, 90-day retention in slack which forces decisions into documentation if it's important, issues/threads for discussions, and handbook for SOPs [1] Anyone have experience with this directly that can speak to if this works in practice? Or is Gitla…

GitLab employee here. Can confirm, it works exactly as advertised to the outside world.

GitLab team member here for over 3 years. Can confirm, it works exactly as advertised. The detailed description above is totally in line with my experience.

The two essential elements of why this works.

1. Communication (both formal — work related — and informal) is explicitly defined. https://about.gitlab.com/handbook/communication/

2. There's absolute executive sponsorship to work "handbook-first." If it's not in the handbook, it's as if it doesn't exist. The top-down belief in the system enables it to function. https://about.gitlab.com/company/culture/all-remote/handbook...

We recently codified the operating model in a course we're calling TeamOps. It's a first iteration, but anyone is welcome to take the course and provide feedback. https://about.gitlab.com/teamops/

Re: High-documentation, low-meeting work culture

#476

Post by RugnirViking »

fool1987 wrote: post #463
nisegami wrote: post #26

In order for this to work, you also need a high-reading work culture, which is distinct from a high-writing (documentation) work culture.

As the only person on my team who routinely documents my work (or at least who does so in a place visible to others), I definitely agree. I get very tired of people asking me things about my work where the reply is "it's in the docs, please check here: ." Makes me feel like a directory.

as someone who often would like to read documentation but have to end up asking the owner where it is like you describe

My problem is that there are too many pages that may or may not be relevant/and/or up-to-date, I want to know if there is a better way? I can't just read every document the company has on the topic in vain hopes for the answer. For example, I recently started working on my company's mobile app - noone has looked at it in a few months so its an ideal candidate for this kind of knowledge.

Despite that, I didn't go to confluence, because 99% of the stuff on there is half-finished drafts, and stuff aimed at our b2b customers, so I don't hold much hope in finding a solution to something which in principle ought to be very simple, like setting up my dev environment. In this case, the original project lead is no longer with the company, I had to ask a couple people who worked with it in the past, and it turns out they no longer knew how, and the documentation which had been written both didn't include it (it was customer-facing) and was also so out-of-date as to be irrelevant. I have no doubt that whatever developer made the app stopped writing documentation because they felt nobody would read it if they did! it's a self-reinforcing cycle.

I guess the only answer, as some others have mentioned, is a predictable organization system for the documentation, which crucially is actually taught to newcomers.

Re: High-documentation, low-meeting work culture

#477

Post by foobarbecue »

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'll say a positive thing about Confluence from the point of view of a mars rover operator. We use it as our main reference on shift and it works great for us. We migrated from twiki and the fact that the search works, everybody can edit easily, and it has a bunch of useful integrations including draw.io . I do wish it had markup or html editing.

Re: High-documentation, low-meeting work culture

#478

Post by bentcorner »

innocentoldguy wrote: post #425
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…

> 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. This comment is absolutely true and many, of not most, companies fail to understand it. I think the problem stems from corporate-people thinking, "Why should I pay a writer when we all speak English (or whatever language) and can write it ourselves." And that's why so many companie…

> I was a software engineer for 30+ years and got completely burned out on it, so I left engineering to do technical writing

How did you make this transition? Any credentials/certifications you needed? Did you transition within the same company?

Re: High-documentation, low-meeting work culture

#479

Post by beckingz »

spencerchubb wrote: post #418
beckingz wrote: post #316

Earlier quoted context omitted.

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?

A human has to write this type of metadata.

If you don't include the right metadata, google won't rank you highly. If you include the right metadata, your content will get higher rankings and the snazzy preview cards on different social media platforms.

Metadata is good! There are structural incentives to be mediocre though.

Re: High-documentation, low-meeting work culture

#480

Post by beckingz »

tshaddox wrote: post #406
hw wrote: post #396

Earlier quoted context omitted.

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.

Agreed. Documentation has upkeep costs as the software and environment change.
Post reply on HN