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

371–380 of 524 posts

Re: High-documentation, low-meeting work culture

#371

Post by satisfice »

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…

I will say the obvious: documentation sucks because good writing is a highly skilled activity that takes a lot of energy for most people to do, AND because keeping it up to date takes a lot of time, no matter how good you are at it, AND because leaders of companies don't want to spend ANY money on tech writers.

That's it. No mystery.

(BTW, this would also be why company financial records would suck, if management decided to save money on accounting staff and have all employees just kinda do their own accounting for the company. I SAY HIRE A SCRIBE FOR EVERY TECHNICAL TEAM!)

Re: High-documentation, low-meeting work culture

#372

Post by pessimizer »

vonnik wrote: post #360

I've worked at high-documentation companies and low-documentation companies. Documentation is hard to create and hard to maintain. It is essentially a simulation of an underlying reality, and that underlying reality *always* changes faster than the documentation can. So the documentation ends up being spotty, except for the parts that you find a way to automate. It's hard to automate all documentation, since so much…

> It is essentially a simulation of an underlying reality, and that underlying reality always changes faster than the documentation can.

That probably depends on how you prioritize it. You can dictate that the docs (and the tests) be written before features are added.

Re: High-documentation, low-meeting work culture

#373

Post by baby »

ericmay wrote: post #135
mr_gibbins wrote: post #128

Earlier quoted context omitted.

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?

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

Usually a tech writer is also some sort of PM role that gets to chase developers and get them to explain what's in their head. Sometimes you have to have such a person on board.

Re: High-documentation, low-meeting work culture

#374

Post by Nevermark »

vonnik wrote: post #360

I've worked at high-documentation companies and low-documentation companies. Documentation is hard to create and hard to maintain. It is essentially a simulation of an underlying reality, and that underlying reality *always* changes faster than the documentation can. So the documentation ends up being spotty, except for the parts that you find a way to automate. It's hard to automate all documentation, since so much…

This can be improved with two sets of links for each doc. A set of manually added links to previous related material, with optional note. New links can be added by anyone.

And a set of automatically generated reverse links, to documents that referenced the one being viewed.

Both kinds of links help create continuity and context.

Re: High-documentation, low-meeting work culture

#375

Post by baby »

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 couldn't disagree more, every ounce of friction that you add to the process of writing documentation is dozens if not hundreds of documents that could have been written and are not going to be.

Unless of course there's a good reason for maintaining your docs in markdown files, but all of them?

Re: High-documentation, low-meeting work culture

#376

Post by rsj_hn »

baby wrote: post #373
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…

Usually a tech writer is also some sort of PM role that gets to chase developers and get them to explain what's in their head. Sometimes you have to have such a person on board.

I once did an internship that involved chasing down senior devs and generating documentation for them (needed for FIPS certification). It was a great way to learn about the tech stack. Suffice it to say I didn't have any PM role at all.

Re: High-documentation, low-meeting work culture

#377

Post by baby »

tiffanyh wrote: post #352

I love the idea of less meetings and more documentation, but I've never seen it work. Here's a few observations... a. you need a person who "curates" the documentation, otherwise it completely loses organization quickly b. things become out of date fast and it's not clear if you're reading something out-of-date c. people write too much, meaning - things turn into this huge long form internal article and people get ex…

I don't think these means that documentation doesn't work. It means that while documentation works, there's a number of additional issues that you also have when you use documentation. Try having no documentation instead of disorganized or outdated documentation. I'll take the latter.

Re: High-documentation, low-meeting work culture

#378

Post by q7xvh97o2pDhNrh »

ebiester wrote: post #30
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…

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 "documentation-heavy" places where (of course) every new hire conducts the ceremonial ritual of updating the docs wherever they could use improvement. I really like having this ontology in my head now; I can see it being very useful.

Also, I wonder if the relative distributions of each one could tell you something about the team's health — or even just the kind of work the team does?

For example, between two teams who are both documentation-heavy, what does it means if one team's docbase is 80% tutorials, whereas the other team's is 80% reference guides? It would be fascinating if anyone's already given thought to relative metrics/heuristics like this.

Re: High-documentation, low-meeting work culture

#379

Post by albedoa »

phailhaus wrote: post #336
albedoa wrote: post #331

Earlier quoted context omitted.

> I have never heard nontechnical people complain about the Confluence wiki. From their perspective, everything Just Works. This is where you lost me and probably many who are following your comments. I have never heard anyone express what you just did about Confluence. I don't know what accounts for the difference between our experiences, but I work with many nontechnical people, and they have a much different opini…

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 never heard nenontechnical people complain about it.

Re: High-documentation, low-meeting work culture

#380

Post by baby »

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…

I really think this is true, and we usually rely on tech leaders or PMs to do this job, but in reality maybe we should consider having people who are responsible for this full time (or at least part time).

I think having advocates or evangelists within the company is important also, people who can interject "good answer, I think it would be valuable to copy this in a document for the next time someone asks"

Post reply on HN