Hacker News Reader

Comment by ebiester | Hacker News Reader

It's an interesting argument. When I hear it, I interpret it as "I'm too busy doing stuff to help anyone else do stuff."

The people who do this, from my experience, are also the people least likely to write tests, documentation, comments, or self-explanatory code. Then, when someone makes a mistake based on misreading this member's code, they are labeled as "incompetent."

I agree that Slack has created an interruptible culture, and I'm not a fan of that, but we have yet to make a tool that transfers knowledge without either human contact or extensive documentation. Structured distraction is the alternative - we call them meetings.

Nobody likes meetings either.

View on HN

I like how you gloss over documentation as if it’s not even a viable solution.

Documentation isn’t hard to generate. Set up a wiki so you can document things there, move your internal “how do I do X” chatter from Slack to email lists and maybe a StackExchange installation, and you end up with multiple indexable, searchable sources of long-form documentation.

Sometimes, documentation is work. So do the work. People and organizations who avoid that kind of work and say “just use Slack” end up trading 1,000 hours of interruption over 1 hour of work.

My personal experience is that the people willing to answer the questions on slack are also the ones who take those answers and put them in documentation so they don't have to keep answering the same questions.

My experience is also that those who don't bother to be responsive to questions aren't pained enough to write the documentation. Further, due to the blindness of expertise, they document the wrong things.

It's precisely the pain of interruption that leads to empathy and good documentation. My team, as one who sources multiple teams, does a significant amount of work in documentation precisely because we know the pain points.

I had a pain point recently when some behavior changed that broke a consumer. I could track to the change, but I couldn't tell why because this person didn't make a meaningful git commit. They didn't create a changelog that explained neither the technical changes nor the product rationale. So, off to slack, and waiting because someone was "too busy" to do any of this.

I have an idea that teams should have a "slack on call" person who rotates daily to interface with other teams. This means that one person is impacted every couple of days. It sort-of works in practice.

I’m not dogmatically opposed to chat, or helping people, or anything like that, and I’ve seen much the same dynamic at play. My problem is more with the culture that arises when conversations move from email to Slack, when interrupting people becomes the preferred mechanism over RTFM, and when I can’t do a goddamn thing without a chat app pinging me because someone @here’d a channel I’m in with something I can’t help with.

Basically, I miss long-form written communication. Slack and PowerPoint are tools that destroy that.

>> Basically, I miss long-form written communication. Slack and PowerPoint are tools that destroy that.

Only if your business allows them to be. We use Slack with specific reasons on how it should be used, with Basecamp as the documentation/project management layer. Slack is not meant to be abused like it is in the article, and the fact that people do it like that isn't a fault of the tool.

That sounds really nice from an idealistic perspective, and I guess Slack's business model isn't as dependent on them focusing on "engagement" over value added, but I still worry.

The problem with Slack and PowerPoint is that they're cheap and easy and you don't necessarily have an incentive to step up from there to full written literacy.

>> idealistic perspective

There is nothing idealistic about it. We use them like that, all the time. It works. It isn't hard. You just instruct your managers that this is how you are going to use it, and you are judged in reviews how well you manage people and projects. If you screw it up enough, you are fired.

You treat documentation and conversation like anything else in the company - not some esoteric thing that gets in the way / assists work. The documentation itself should be subject to performance review, and in our company, it is.

We get what we incentivize. Unsurprisingly, we have good documentation and good communication throughout.

You may have tried this / it may not help. We have dedicated help channels - a company-wide 'help' (for anything, but normally related to technical issues or looking for general advice on a topic where you don't know who could help), and product / team-specific help channels. There's no need to @here those channels, because there's already the intermediate-level flag of "this channel has new messages, meaning someone needs help" without going all all the way to "notify everyone".

There are enough people around that someone will take a look at the channel in the near future, and they can either answer or point you to a good person to ask, at which point you're back to non-slack-specific style comms i.e. "I want to contact person X, I can either interupt them or send them some async comms".

I probably get 1 or 0 notifications a day from channels as opposed to DMs - there's just no need to @here if you have specific channels for certain types of request.

> when interrupting people becomes the preferred mechanism over RTFM

Oh god, this is the bane of my existence. Slack, skype, even in-person. Some people will never read the docs. They will seek out people who "know" and disturb them. Earlier they would fire off an email. Now I'll get a message at 2am when I just want to get this last commit in and go to sleep.

So you may be right about responding to @soandso, or even &here. The problem isn't responding to those, it's feeling the need to constantly be reading and responding to random conversations that should have actually been a scheduled meeting with an agenda. Or worse constantly checking back for all the random hits of dopamine you get from pretending that reading random low quality comments is actually work. Working on anything but the most basic of features requires getting your head in the right place, and as such you should be expected to ignore chat for sometimes hours at a time.

Everywhere I've ever worked, "set up a wiki" has meant "create something once that nobody ever remembers the existence of"

Or, it accumulates so much cruft that it's hard to find the valuable information. I think there's room for documentation librarians, whether by role or job title, but it's hard to justify the expense in smaller organizations.

I found that a bit of scripting will make a wiki a bit more maintainable. Replace pages that are out of date with a tag of some sort (e.g. #outdated). Have a script spider the wiki from the home page and send out an email with all the reachable pages with tags. Either fix the page or make sure it’s no longer reachable.

Pro librarian work right here, Nice work!

It's a trained skill - everyone can be a librarian in the team.

One person needs to lead the standards and the organization or the conflicting opinions will drive it apart. The librarian is a role, but that doesn't absolve the rest of the team from following the librarian's lead.

In my experience, documentation stored in source control alongside the code gets updated and maintained. Documentation stored in a wiki is left to rot.

For code documentation, that's definitely true, but you need places to document processes, designs, and other things like that.

Out of sight out of mind is one component of this. The other is how easily you find the documentation. Most people are willing to document if it's easy to do so, and most people will read the docs if they're easy to find.

Everywhere I've worked with wiki, I found that people actually read the wiki and that it contained both important guides for new users/developers/maintainers and old documentation that was crucial for old systems.

The last three corporate wikis that I have worked with have tended to contain some very useful and well maintained sections detailing stuff like developer machine setup and tooling.

They have also contained large amounts of information from separate projects, none of it which was relevant to my task at hand, and on top of that they have contained a wasteland of obsolete pages, the contents of which was trusted by no one.

I don't have a problem with the concept of a Wiki per se but I do have issues with treating them as a magical virtual haystack on top of which you can shovel information and from the midst of which you can painlessly extract needles.

I swear there's a startup in there... I have some ideas to combat it. It will probably rattle in my brain for another year until someone has already come up with a "good enough" solution and I'll lament that I didn't go for it.

(Life circumstances have me away from the startup life at the moment.)

I think that if search worked, the Wiki could be a great hub of information.

For the search to work, it should make an effort to get to know you, that is, try to track which pages you have previously edited or opened, or maybe it could access information about which project you are currently assigned to in JIRA or which internal repositories you have recently committed to in git. Also, which pages are popular, which pages are mainteined, etc. This would enable its search engine to filter bubble you and provide far better results that I currently see Confluence doing.

Further, it should be able to contain pages which are just indexed mirrors of other resources. Some pages could be simply uneditable mirrors of markdown files in your repository, making it possible for developers to keep documentation alongside the code if this makes more sense to them. Other pages could be mirrors of Word documents or Excel sheets of PDF files on shared drives or where the company likes to keep this stuff. All of this stuff would be thoroughly indexed by the wiki and would show up in search results.

So I guess what I'm proposing is that wikis become an aggregator of information more than a single store of information. And that they really, really nail the search part.

You've essentially described pagerank. Pagerank's patent just expired. Hopefully, that means it will start appearing in wikis.

Yeah, I probably did. The "personal filter bubble" thing is very much how google does it. I don't know the details about pagerank but I imagine that they are constantly tweaking their secret sauce to increase revenue and that they would rather keep the juicy parts secret than having them described in details in a patent. Also, I'd imagine that other search engines, such as Bing, have developed similar algorithms although I'm sure thay take great care not to infringe upon the pagerank patent.

Disclaimer: Purely conjecture on my part. No particular knowledge of patent law, and only a high level understanding of the pagerant algorithm.

Better have a wiki with some obsolete pages than have nothing and no documentation at all.

True dat. Writing no documentation is also a bad path.

Personally I've come to favor keeping the technical documentation close to the code. That is, keep it as markdown files and check it into git. They are just as easily hyperlinked to as a wiki page on the bitbucket web interface (or whichever system is used). The main README.md should contain information on how to set up the dev environment. Other README.md files, located in the folder root of modules, provide more specific information.

Documentation of a less technical nature may still find a natural home in the Wiki, since we also need a place where various managers, testers, salespeople, support people, etc. can maintain their documentation.

Because writing the documentation is work and seems hard so people don’t do it.

Also, nobody can ever find again, even if they remember. And then they will create a whole new page for the same thing plus a small addition. Then 6 months later some poor soul will notice that you have 10 pages on how to do X and he will delete everything and consolidate them all into one page. Then the cycle begins again. Wikis are fucking useless.

Too many developers simply refuse to do documentation or half-ass it. Developers who write good documentation are not valued or rewarded by companies and teams. Instead the teams grows to expect them to do all of it (while also considering them lesser because they don't do less cool stuff). Hence complete circle.

Unfortunately, not documenting seems to be part of culture.

> move your internal “how do I do X” chatter from Slack to email lists and maybe a StackExchange installation, and you end up with multiple indexable, searchable sources of long-form documentation.

Really, those stores of "long term" documentation complement chat rather than replace it (whether it's Slack, IRC, or whatever). Over time, you should be developing that documentation, so when you have repeated "how do I do X" type of questions in chat, you can often direct people straight to the docs.

But documentation is never foolproof. It's inevitably incomplete, it goes out of date, etc. And for the information that the docs don't cover, you want a real time asynchronous discussion that's not as heavy-weight as a meeting or as slow as email, which is a good fit for chat.

In my experience, it's chat that drives the documentation.

Chat is many things, but “asynchronous” is not often one of them.

Chat is absolutely asynchronous. It supports synchronous discussion, but I specifically like chat because I can ignore it until I dedicate a few minutes to look through the notifications.

You're lucky then. IMs are by their design pretty asynchronous, but there is this common dysfunction in many organizations - expecting you to be constantly on the chat and participate in real-time. That's the organization turning an asynchronous tool into a synchronous one, true, chats tend to facilitate that dysfunction much more than e-mail.

Slack, unintentionally, promotes interruptions under the guise of frictionless communications; it's very difficult to cultivate productivity in such a situation. Email is just as useful for tasking or questions, but without the constant interruptions (the receiver determines when they respond, and there's an asynchronous expectation, unlike Slack).

There is nothing you need on a team immediately, unless your infrastructure is burning down, in which case PagerDuty or SMS is letting you know.

Source: 3 years of Slack use in a fully remote environment, now working remote for an enterprise using Outlook for email, MS Teams for the occasional group chat 1-2 times/week, and Skype chat/phone calls/conference calls for the remainder. I prefer the later, as I get hours of uninterrupted time to focus each day.

My impression is that companies that use Slack as an email replacement (including Slack themselves) have a culture where it's common to turn off push notifications / popups and check Slack periodically the way you'd check email periodically.

It's a been a year since I used slack but I distinctively remember that they didn't have anything to manage notifications / popups.

Possibly. That was not my experience ("turn off push notifications / popups and check Slack periodically the way you'd check email periodically.").

I use Slack extensively for personal needs (non-profits, subject matter groups, friends/family teams) but I would not voluntarily use it in a business setting. It's one of the first questions I ask when interviewing for new positions.

Hmm

As I get older I dislike meetings less, especially 1:1s. One-on-ones are usually the high point of my day.

This is just the same problem everyone has with everything. Tools are useful but you need good culture built around those tools. Slack is great for getting help, or discussing a topic in real time, especially when you're canvasing for views. But it's incumbent on the people to be sure they're contributing to it appropriately. A classic trap young engineers fall into is spewing questions when they haven't thought about something for themselves. In that environment Slack can be very destructive.

The fact that this guy repeatedly refers to middle management kind of hints to me that he doesn't understand that culture aspect.

> I agree that Slack has created an interruptible culture

Slack isn't the first chat app used in a workspace, but it is the first one I've used that has tweakable mute settings and filters that can alert me only about things I care about.

At my previous jobs I've used IRC or Google Hangouts/Talk which is equally interrupting but has less features.

Reply on news.ycombinator.com