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

131–140 of 524 posts

Re: High-documentation, low-meeting work culture

#131

Post by namdnay »

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?

My experience is that for internal documentation the time spent explaining things to a technical writer is bigger than the time spent writing the documentation

This isn’t the case for external documentation, that has to be more polished, needs sign offs and images and demos and stuff - tech writers can come in useful here

Re: High-documentation, low-meeting work culture

#132

Post by origin_path »

cmdrriker wrote: post #119
triceratops wrote: post #60

Earlier quoted context omitted.

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

Does it matter what tool you use to write documentation? Confluence gets a lot of sh*t because its in the grown-up camp of tools but I know people who've got problems even with nano. It's incumbent upon all users or members of the team to use the common tool along with agreed upon standards. Otherwise even if you wrote documentation in your own hemoglobin, no one would touch it either. Some manager prob chose _______…

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 make docs work you have to treat it more like a codebase: clear ownership, standards, review processes, approvals, up front design, refactoring efforts etc.

Re: High-documentation, low-meeting work culture

#133

Post by googlryas »

capableweb wrote: post #51
c54 wrote: post #47

Earlier quoted context omitted.

Diataxis looks interesting thanks for the link

Wow yeah, it puts into much better words than what I've been trying to get software engineers to do for a decade or more. Really awesome resource, thanks again kind parent :)

The nice thing about this as well is that, unlike a technical framework, you can start implementing many of the ideas of this framework without any sign on from the rest of your group. And if it works, what will eventually happen is people will say "wow, capableweb rights such fantastic documentation, we should go to them and ask for their advice on how we can all write documentation that good"

Re: High-documentation, low-meeting work culture

#134

Post by rcarr »

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 departments add, commit and push and then show maybe one person from each department how to solve conflicts. Alternatively, build non technical people a web interface for editing and committing but allow the devs to just use git as standard. Or there's Obsidian's built in sync but I don't know enough about it to know if it scales well in large organisations.

What absolutely is definitely not the solution is Confluence. I have not met anyone who has a positive thing to say about it. The only reason it is being so widely used is because it satisfies whoever is in charge of the finances because it comes bundled with Bitbucket and Jira.

Re: High-documentation, low-meeting work culture

#135

Post by ericmay »

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?

> 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 question why not make twice as much working as a software developer and not have to sort out these types of messes?

Also job security. Anyone doing this work full-time is the first on the chopping block, and developers who are working on documentation tend to be perceived as lower status since they aren't delivering features.

Re: High-documentation, low-meeting work culture

#136

Post by fsociety »

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.

Ha I hear this a lot but the alternatives I have seen used are frankly just as terrible. I much prefer Confluence to a hidden web of Google docs.

Re: High-documentation, low-meeting work culture

#137

Post by cateblanchett »

kozak wrote: post #101

"Unfortunately, Tremendous is not available in the country where you are located. If this is a problem, please contact support@tremendous.com." I'm in Ukraine and this is disgusting.

US treasury department regulations prohibit US companies from working with people and companies in Russian-controlled parts of Ukraine. Unfortunately, IP geolocation is accurate only to the country level, so US companies have no choice but to block the entire country to comply with regs.

Re: High-documentation, low-meeting work culture

#138

Post by FooBarWidget »

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…

What's the difference between Diataxis and the Divio documentation framework? https://documentation.divio.com/

Re: High-documentation, low-meeting work culture

#139

Post by Xeoncross »

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 service, and other backgrounds who can spot trash (in their area of expertise) when they see it.

Re: High-documentation, low-meeting work culture

#140

Post by waboremo »

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…

An easier one stop shop alternative is just Notion. Recommend it for the reason of having an internal wiki/documentation. Probably one of the only real use cases for Notion, everything else (like personal note taking or time organization) is horrible on it.
Post reply on HN