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

191–200 of 524 posts

Re: High-documentation, low-meeting work culture

#191

Post by vasco »

rcarr wrote: post #183
koonsolo wrote: post #160

Earlier quoted context omitted.

That is indeed too technical. Try to explain how inserting an image is not just copy paste.

1. Paste image into assets folder. 2. Write ![imagename](imagename.jpg). It's not that hard really is it.

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 image, and ask a developer to help them out.

Re: High-documentation, low-meeting work culture

#192

Post by nickdothutton »

All the corp document stores I’ve seen, and I think I’ve probably seen most of them by now, would benefit from a full-time librarian (or team thereof) and a help-desk to field enquiries. Because you have little hope of finding what you want, even if you know it’s in there somewhere.

Re: High-documentation, low-meeting work culture

#193

Post by whatshisface »

neura wrote: post #173
whatshisface wrote: post #110

Earlier quoted context omitted.

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?

Being as you put it the "gatekeeper" advertises their importance to everyone in the company who needs to know about the processes, making advancement easier and guarding against anyone thinking they are not necessary.

Re: High-documentation, low-meeting work culture

#194

Post by PartiallyTyped »

j7ake wrote: post #145
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 find Dropbox to have much less friction (almost zero) compared to git. In the teams with nontechnical people it is often enough to just use Dropbox. Git requires manually committing, which is friction and people often forget to commit changes. The fact you need one person technical enough to resolve conflicts is already a deal breaker.

Setup a service with Dropbox sdk and python to pull the data, commit them, and push (even forced) to git.

At least you will have multiple revisions.

Re: High-documentation, low-meeting work culture

#195

Post by danny_codes »

simmschi wrote: post #111
gmd63 wrote: post #94

Earlier quoted context omitted.

No, code actualizes the intent of the documentation and the product. The natural language description of a product shouldn't need to be discarded in lieu of some machine language. The lingua franca of ideas is natural language.

Fair enough, but you still end up with 2 separate ways to express things. And I have yet to see a company that changes the documentation first and then derives code changes from that. Usually tickets are written, code is changed. Updating existing documentation is an afterthought at best. Personally I prefer any formal or semi-formal documentation (e.g. Swagger) over a Confluence page any time of the day.

I think most of us approach documentation without intention. We write to express the idea, but fail to consider how the documentation fits into the deliverable.

For example, one could structure things where the English documentation is the deliverable. The code merely serves to actualize the document. In this world, we would consider the act of writing documentation of paramout importance, whereas the code is an implementation detail.

I think software as a discipline is distinctly undiscipled about these sorts of concepts.

Re: High-documentation, low-meeting work culture

#196

Post by csharpminor »

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 don't like Confluence either, but the platform is only 10% of the problem. Knowledge Management platforms are something that PMs love to debate, purchase, and use to get promotions. So you end up with a company that has 6+ platforms. This is way worse than having one unified, crappy-UX, wiki.

Finding the perfect documentation platform becomes a waiting-for-superman game. Everyone loves to complain, but nobody wants to put in the actual work to write clear content, define information structure, consider audience, etc.

The real solution is hiring people who are excellent writers. To do this, leadership must be good at reading and writing themselves (not a given) and be able to recognize top contributors.

Re: High-documentation, low-meeting work culture

#197

Post by rcarr »

ravenstine wrote: post #175
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…

I do think just using the folder of markdown folders is far preferable to browsing on the web wherever possible but there's definite use cases where it's unavoidable. I do think this is a very strong case for using Obsidian however, because you literally don't have to mess about with maintaining any kind of SSG, you just put `publish: true` in the metadata of whatever note you want publishing and then just click the Publish button and it's there on the website.

Re: High-documentation, low-meeting work culture

#198

Post by WorldMaker »

joegahona wrote: post #181
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…

> Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people. How do you find a happy medium between this and a Confluence-like free-for-all, where anyone can create/edit a page?

There are Wiki-like interfaces for git+Markdown: GitHub's wikis, gitit, and more.

Re: High-documentation, low-meeting work culture

#199

Post by k__ »

joegahona wrote: post #184
FooBarWidget wrote: post #138

Earlier quoted context omitted.

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

Indeed, they look identical, even down to the font used.

Diataxis seems to be a fork of Divio.

But according to the network graph on GitHub, Diataxis seems to be more active, although both of them still receive updates.

Re: High-documentation, low-meeting work culture

#200

Post by primax »

Terretta wrote: post #162
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 which is just rendered on the web either using a simple static site generator or using Obsidian Publish This, except for normals, sort of exists: Craft: https://www.craft.do/solutions/businesses Default is internal only, but you can allow sharing, which creates a web URL that can be priv…

This looks great, but no Android or mobile support outside iOS is a big negative
Post reply on HN