Hacker News Reader

Comment by polote | Hacker News Reader

This is one of the articles which is pure non sense, but helps drive a rich HN discussion on the topic discussed.

The idea is a very bad idea. Imagine if wikipedia would do that, what will happen. Fortunately they don't and they found other way to fix the problem.

The issue here is: part of the documentation is not up to date anymore

The underlying issue is : the culture of the company probably doesn't encourage written documentation and probably prefer 1-1 communication. As a result documentation is out of date

The right solution is: Dont share documentation in 1-1, always write it on the wiki, and give the ability to people to notify that some part of the page is out of date so that the owner of the document can fix it

This is not a side issue, especially in the "new" world in which a lot of organizations need to work remotely

View on HN

Don't share documentation 1-1: Set your Slack retention ridiculously low to force people to put information in documentation if they wish it to be retained at all.

This is one of those instances of pure non-sense that I hope will drive rich discussion.

As with every other attempt to "force people" to do something via UX limitations, I think that's doomed to fail.

The whole notion of forcing users to change their behavior by placing obstacles in their way is futile in my experience. It's a grave misunderstanding of who users are and how to design for them.

Forcing users to do what you want them to is how you get desire paths [1]

[1]: https://en.wikipedia.org/wiki/Desire_path

> Set your Slack retention ridiculously low to force people to put information in documentation if they wish it to be retained at all.

I worked at a company that tried something similar.

The result was that individual teams set up their own off-the-record private Slack workspaces or Discords so they could regain some control over their conversation history. Obviously not great from a company information security perspective, but many managers looked the other way because they just wanted to get their work done without worrying about conversation history arbitrarily disappearing.

The idea that you can force people to produce better documentation by making their lives more difficult never really works out.

The issue with 1-1 communication is not the retention part but the exclusive and not complete part. If you have no retention but allow 1-1, the same person will just keep asking the same question over and over. Which will make everything worst.

Also as the sibling comment is saying, you won't change the culture of an organization only by an UX change or a software change, that can help, but that won't be enough

When you say don’t share documentation 1:1, do you mean always share broadly? Or do you mean always write it down?

Terrible idea indeed. Why would I opt for a one year storage option when I could send an email blast with the info and have it retrievable for a lot longer?

This would push people away from a wiki.

I think what this idea is calling out is that whatever you sent in the email a year ago is probably stale now - it answers the question for that time, but not necessarily for right now, whereas a wiki should have versioning.

Unfortunately once you update the wiki, it also grows stale after that moment, so in someways intractable :)

Perhaps that’s not a bad thing.

You want to encourage thorough and up to date documentation? Don't allow code to be merged without docs. Review documentation at least as stringently as code. Insist on clear exposition, good grammar, and accuracy. If you're not willing to pay that price, your docs will only be as good as your programmers' intrinsic motivation to write them.

The fact that I have never been able to get buy-in for this proposal would argue that our docs may actually be good enough.

> Imagine if wikipedia would do that

That's not the use case the blog post is addressing. It shouldn't be considered a mark against anyone if when applying their advice in a way that they never advocated then it turns out not to hold up so well.

I’m not sure if Wikipedia is a fair comparison but open minded - what I appreciate about this approach is it forces the org to think from first principles about what should be in their knowledge base.

What else do you see causing the problem aside from culture? Are there tools that do this well?

> The right solution is: Dont share documentation in 1-1, always write it on the wiki

You are restating the problem, the question is how

Not really. "Get people to always add to the wiki" is a different problem than "don't have 'outdated' pages on the wiki".

Reply on news.ycombinator.com