High-documentation, low-meeting work culture • Hacker News Board

Re: High-documentation, low-meeting work culture

#211

Post by stcredzero » Tue, Nov 22, 2022, 8:45 PM UTC

PragmaticPulp wrote: post #158

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 know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writin…

> This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow

Given the number of non-programmers who Really Need the functionality of git, who probably won't be able to hack dealing with it, doesn't this indicate that there's some huge vein of untapped value to be won by whomever cracks the problem? (Version control for business people?)

Re: High-documentation, low-meeting work culture

#212

Post by dist1ll » Tue, Nov 22, 2022, 8:45 PM UTC

holoduke wrote: post #189

Documentation is worse than code. It's often outdated, difficult to understand and full of useless information. In every company I have been people hate to read docs and nobody wants to maintain them. I am not sure what a good alternative might be.

That's a culture problem. It boils down to documentation being a second-class citizen which is not included in the "definition of done".

Re: High-documentation, low-meeting work culture

#213

Post by [deleted] » Tue, Nov 22, 2022, 8:45 PM UTC

rcarr wrote: post #159

waboremo wrote: post #140

Earlier quoted context omitted.

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.

This was actually my next suggestion when Obsidian got shot down. It's definitely a nice half way house between the two. Again it got dismissed albeit this time with no explanation, I assume because the request for feedback and suggestions wasn't actually anything of the sort but basically a pretend exercise on behalf of management to 'show we're listening'.

[deleted]

Re: High-documentation, low-meeting work culture

#214

Post by DubiousPusher » Tue, Nov 22, 2022, 8:45 PM UTC

I think this approach has many benefits. The main problem with most collaborations in which documents are used to replace conversation is that without a disciplined framework for structuring documents it's very easy to get lost in them.

-documents go out of date, people are usually up to the minute

-documents don't allow you to ask questions people do

-documents never forget, people do (not forgetting seems like a good thing but try working through a 5-10 year old team wiki or OneNote and you'll see why it can be good)

Re: High-documentation, low-meeting work culture

#215

Post by kfrzcode » Tue, Nov 22, 2022, 8:46 PM UTC

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 like Confluence! It serves it purposes and provides a lot of niceties, and is - as you mention - integrated with other Atlassian tooling. Nice ecosystem!

Re: High-documentation, low-meeting work culture

#216

Post by user3939382 » Tue, Nov 22, 2022, 8:47 PM UTC

PragmaticPulp wrote: post #158

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 know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writin…

The Google Docs/Sheets version history strikes a pretty good balance of friendliness and power. The biggest weakness I've seen with it in the hands of non-technical users is that they don't know it's there.

Re: High-documentation, low-meeting work culture

#217

Post by nonethewiser » Tue, Nov 22, 2022, 8:47 PM UTC

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…

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

How is this not inevitable if your goal is to always write things down? It seems like the way for document to be accurate is to keep the scope small and if you want everything in scope then it's going to contain a lot of outdated information.

Re: High-documentation, low-meeting work culture

#218

Post by Whitespace » Tue, Nov 22, 2022, 8:48 PM UTC

FooBarWidget wrote: post #138

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…

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

Seems like the Diataxis author came up with the framework while working at Divio: https://github.com/evildmp/diataxis-documentation-framework/...

Re: High-documentation, low-meeting work culture

#219

Post by mym1990 » Tue, Nov 22, 2022, 8:48 PM UTC

someguydave wrote: post #204

vasco wrote: post #191

Earlier quoted context omitted.

Have you worked with non-technical teams, ever? Perhaps in teams of very young and gamer-type people this would work, but in any real world team I've been in, this would not in fact be easy unless there's a real time preview and a button you can click that auto-generates that snippet. People would forget the exclamation mark, mixup the brackets with the parenthesis, not know how to reference the right path to the ima…

If someone is confused by markdown syntax it is hard to imagine how they contribute professionally.

Maybe you should try to imagine a little harder. "If You Judge a Fish by Its Ability to Climb a Tree, It Will Live Its Whole Life Believing that It is Stupid"...or in this case you will live your whole life believing every non-technical person around you is stupid...which just sounds miserable for everyone involved.

Re: High-documentation, low-meeting work culture

#220

Post by jonwest » Tue, Nov 22, 2022, 8:48 PM UTC

rcarr wrote: post #174

PragmaticPulp wrote: post #158

Earlier quoted context omitted.

> I know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writin…

I do get what you're saying because I struggled with it for ages. There are good GUI tools like Sublime Merge for easy conflict resolution now which would be one solution. I do think a web interface that just automatically commits by just adding your text in addition to the new text along with a warning would probably be the easiest solution and then just have someone edit it after the fact. It's not been my experien…

GitHub does offer the ability to modify files within the web UI and open a PR from there.