4 ms·

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 wikip

by polote 6y ago

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

godzillabrennus 6y ago
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.
- chris_wot 6y ago
  Perhaps that’s not a bad thing.
- harrisonjohnson 6y ago
  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 :)
VectorLock 6y ago
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.
- CathedralBorrow 6y ago
  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 https://en.wikipedia.org/wiki/Desire_path
- polote 6y ago
  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
- PragmaticPulp 6y ago
  > 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.
- harrisonjohnson 6y ago
  When you say don’t share documentation 1:1, do you mean always share broadly? Or do you mean always write it down?
sevensor 6y ago
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.
kindofastrawman 6y ago
> 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.
thinkloop 6y ago
> 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
- detaro 6y ago
  Not really. "Get people to always add to the wiki" is a different problem than "don't have 'outdated' pages on the wiki".
harrisonjohnson 6y ago
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?

by polote 6y ago

godzillabrennus 6y ago

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.

chris_wot 6y ago
Perhaps that’s not a bad thing.
harrisonjohnson 6y ago
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 :)

VectorLock 6y ago

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.

CathedralBorrow 6y ago
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 https://en.wikipedia.org/wiki/Desire_path
polote 6y ago
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
PragmaticPulp 6y ago
> 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.
harrisonjohnson 6y ago
When you say don’t share documentation 1:1, do you mean always share broadly? Or do you mean always write it down?

sevensor 6y ago

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.

kindofastrawman 6y ago

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

thinkloop 6y ago

> 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

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

harrisonjohnson 6y ago

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?