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

171–180 of 524 posts

Re: High-documentation, low-meeting work culture

#171

Post by triceratops »

PragmaticPulp wrote: post #163
triceratops wrote: post #154

Earlier quoted context omitted.

If using the lowest friction or default path in a tool leads to bad outcomes, that's a problem with the tool. Not the user.

You create the lowest friction/default path according to your company's needs. There isn't a universal note taking application that comes pre-organized for your team's use case. You have to put some work into any tool you use.

I disagree. The point of a tool is to reduce work.

Most teams and companies aren't special snowflakes that need individualized organizations, and document hierarchies. There can be such a thing as sensible defaults that you customize or tweak later (no idea if Confluence ships with that - I've only ever seen Confluence installations in their already-screwed-up state). At the same time, an inexperienced user staring at a fresh Confluence install isn't going to get the organization correct right off the bat.

If you have to put in work upfront before the tool is even halfway useful, it better be really damn good after that. Confluence is not.

Re: High-documentation, low-meeting work culture

#172

Post by antupis »

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…

This might be stupid question but why nobody has not built this kind git-based system to nontechnical people.

Re: High-documentation, low-meeting work culture

#173

Post by neura »

whatshisface wrote: post #110
neura wrote: post #87

Earlier quoted context omitted.

So you are now the gatekeeper?

If an individual employee is going to put all that work in without being asked to or being given scheduled time to work on it they should get something in return.

In the above scenario, I do not understand what they are getting in return.

Are you saying this person should be hired/paid to store and retrieve the information being sought out?

Re: High-documentation, low-meeting work culture

#174

Post by rcarr »

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…

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 experience that there's a hell of a lot of merge conflicts going on with documentation anyway but I could see how it could happen if you had multiple non technical people actively working on a project.

Another not great but possible solution could be for non technical people to work on something like a Google Doc when stuff is in highly active development and to then copy this to a markdown document later when its solidified.

I do think that as a society we have to start looking at stuff like this as a new essential skill though. We wouldn't expect people to be working without basic literacy, numeracy and computer skills and I think we are going to have to start looking at upgrading our sense of what basic computer skills entails to include stuff like git and teaching it in schools from an early age.

Re: High-documentation, low-meeting work culture

#175

Post by ravenstine »

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 wouldn't even bother with the static site generator. While I like the idea of STGs, in my opinion, they all suck. And now there has to be someone to maintain how those pages are rendered and know how whatever thing like Jekyll works.

Just let developers either read the markdown files as-is or set their IDE to render markdown previews by default. I prefer the latter because I don't have to wait for someone who's on vacation half the time to render the latest docs.

When it comes to API documentation, everything should just be inline comments in the doc format of choice for the team. Don't bother rendering this out, because every flipping tool ever invented for converting inline documentation into HTML fails on something simple. Developers can read the inline docs as-is and/or rely on their IDE to provide them hints from those docs.

If you have to deploy your documentation, that's how you know you might as well give up. It's one thing to deploy documentation for 3rd parties, but for documentation being used internally there's few good reasons to turn the documentation into its own website. That's extra work that I've never seen increase productivity or developer happiness. Don't put documentation behind one or two guys with special permissions to press a deploy button. If you do, the documentation will always be out of date as soon as it's rendered.

Remove as many reasons that devs won't write documentation as you possibly can.

Re: High-documentation, low-meeting work culture

#176

Post by rcarr »

tomxor wrote: post #170
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'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git I had the same concern, internal documentation should be in a portable format... and I managed to mostly successfully get us to change to MD text files in a git repo. I, and others, were tired of it being locked up in proprietary platforms like google docs - which ironically has terrible…

Hadn't heard of this before, looks very cool. For anyone interested: https://github.com/claudioc/jingo

Re: High-documentation, low-meeting work culture

#177

Post by lifeisstillgood »

>>> It’s not just about the meeting, which is itself a thirty to sixty-minute intrusion on someone’s day. It’s about the time wasted anticipating a meeting, where people feel they don’t have the time to plunge into an important project.

Oh god yes! This - a thousand times this !!

Re: High-documentation, low-meeting work culture

#178

Post by Terretta »

antupis wrote: post #172
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…

This might be stupid question but why nobody has not built this kind git-based system to nontechnical people.

https://www.craft.do

Re: High-documentation, low-meeting work culture

#179

Post by loudmax »

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…

This is what the Gitlab wiki does. There's a markdown+git interface for technical folks and a web interface for normal people.

Re: High-documentation, low-meeting work culture

#180

Post by lastofus »

antupis wrote: post #172
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…

This might be stupid question but why nobody has not built this kind git-based system to nontechnical people.

Some people have built it. For example: https://www.macupdate.com/app/mac/49459/draft-control
Post reply on HN