I also don't understand it from the perspective of the business.
Instead of having information available publicly that can be found via Google or browsing a help portal/documentation website, they want everyone to drop into a chat room and ask a question that most likely already was answered before?
It just adds further work for yourself as well. Yes yes, I know that many won't even touch the help portal/documentation and ask questions regardless, but even if 10% could be helped by self-serve support, wouldn't it be worth it to keep something like that up to date instead?
Google is increasingly useless at surfacing relevant documentation (it prefers SEO blogspam).
The ability to talk directly to a real human is really powerful. I'd rather it wasn't Discord, but it is the lowest friction way of putting people in touch right now - at least, those within a certain demographic.
There are many alternatives to Discord, self-hosted or otherwise, but nothing else comes close in terms of the audience you can reach.
I don't think docs should live in Discord, but I can see why they end up like that.
Give me an example of a search for a given tools documentation that doesn’t have the result on the first page. Google seo is bad but I think this is hyperbole because I use it to find documentation easily most every day.
Some of these resources are alright, but none of them are python.org or other primary source. As a python user and google expert, I know how to tweak my query to get better results, but if I was a novice I wouldn't.
On the other hand, if I went to the python community discord server, I'd probably get a sensible response from a real human in seconds. (the python discord is particularly excellent, by the way)
But why would a novice care if it came from python.org, providing the information was accurate? I don't think you've found a good example of what the GP was asking for, at any rate. I've certainly had that experience recently, but it turns out it was something more obscure than I would have expected (relating to ensuring that gulp scripts don't return an error code when warnings occur - I'd searched for `gulp --warnoff` and none of the answers were anything to do with the gulp tool, but it turned out "--warnoff" wasn't a standard flag anyway, though there is a blog post about how to add support for such a flag).
It doesn't seem like python.org answers the question very well? As in the implied question of "What is python __init__?"
The returned sites do?
If I google "php __construct" I get php documentation as the first result.
Google knows when someone doesn't find the answer they're looking for from a result, I suspect the results you're seeing are the ones the majority of searchers for that query wanted.
> The instantiation operation (“calling” a class object) creates an empty object. Many classes like to create objects with instances customized to a specific initial state. Therefore a class may define a special method named __init__(), like this:
def __init__(self):
self.data = []
> When a class defines an __init__() method, class instantiation automatically invokes __init__() for the newly created class instance. So in this example, a new, initialized instance can be obtained by:
x = MyClass()
Seems like a good explanation to me? Maybe people are upset that it's buried a bit in the docs instead of having a tiny out of context statement about it?
Yes, I suspect people saw a wall of text and went back to look for a shorter answer.
I would guess google A/B tested those results till python.org fell off the front page.
More to the point, I don't think either google or the people searching are wrong for that. The query isn't "teach me about python classes" it's "what is python __init__?".
Yea, I used to get annoyed when I saw results like this. But I appreciate them more and more. It's still easy to find what you're looking for with a quick Ctrl+F. But there inevitably comes a time when I want to understand a concept deeper, and I can come back to results like this for the longer explanation.
I know that it doesn't have to be either a long explanation or a quick and concise snippet of information, it can be both. But I find that a lot of docs will either have long explanations or short snippets (because time is finite and doing both is duplicating efforts), and in those cases, I prefer the long explanation.
Thats not what I mean by using a search engine to parse documentation. I would just type “python documentation” where the first link I get is the documentation. Then I would search within that documentation for “ __init__” which, when tested just now, took me about 30 seconds all in to get to the known good source of truth here. That’s pretty good I think.
It's still good for finding documentation if you know the domain it's hosted on, which for product documentation you should. Just add "site:documentation.com" to your search query.
> The ability to talk directly to a real human is really powerful.
100%. But different strokes for different folks, as well as at different times in the evaluation/discovery journey. Many devs don't want to talk to someone.
From the perspective of the product company, things are a bit different. If you are pre-product market fit, you probably want every interaction with a possible customer/user you can, so you can move towards understanding the problem space. Set up discord for that.
Once you find PMF, it's all about setting yourself up for scaling. We made a choice to scale back chat and focus on online, public forums, and it worked out well for us. If you want to talk to a human, you can absolutely engage with our sales team, or in other public spaces like Twitter.
That said, some projects are big enough or inspire enough people that the community can scale on discord. Haven't seen that often, but it happens.
> Google is increasingly useless at surfacing relevant documentation (it prefers SEO blogspam).
Agree for generic programming queries, but for product specific queries, I haven't noticed that. And product specific queries are what documentation and forum are designed to help with.
This isn't a new problem. I was doing some classic iPod research a while back, looking back on mid-00s hardware research. Some knowledge was present only in IRC chat logs, and some is surely lost to the sands of time. Similar story with PDA hacking.
The knowledge still needs to be transferred to wikis etc. so that it can be preserved long-term.
The problem is that users type in "how to do X" into Google. End users often enough don't even know the website of your application, I know so many people who literally go to Netflix by typing in "Netflix" in the bar and click the first link.
But Google has dumbed down so hard that scammers using generic keywords outcompete everyone including yourself (or outright clone/farm SO/Wikipedia/whatever), which is why many people add "stackoverflow" or "reddit" to the search terms, and the latter broke a few weeks ago when many subs went private.
The most annoying thing is, Google could shut down a lot of these scammers if they would invest in a couple hundred people to look at the most frequent questions and rate the top 20 sites - everyone caught to be a blatant spammer gets the boot, and everyone selling fake dick enlargement pills or whatever gets the police with the full support of the billions of dollars of Google. But they seem to have completely stopped all effort into their core product...
I suspect they've figured out that whole search engine business model thing has been deprecated for months in its current form. Their product has been shitty in specific areas for several years now.
Google being ran internally akin to the Soviet union has lead to a competitive advantage being not just lost, but far surpassed. As nature intended.
The majority of the time they aren’t thinking about the customer, they’re (selfishly, or naively?) thinking about themselves and how they can crowd source their support versus providing real personal solutions.
> I also don't understand it from the perspective of the business.
Is it a "Gen Z-thing"? Discord is already very popular in that segment, so if a company wants to engage with younger customers/users - or has a younger team-members calling the shots, then that would make-sense.
I don't think there's necessarily a problem with a company operating a Discord server for purposes of community engagement or marketing. But that's an entirely different thing than using Discord as a support platform.
Honestly, I’d take it over other archaic forms of documentation that came before. These are, off the top of my head, the things Discord solves:
Documentation that requires you to sign up to yet another website.
Paying for documentation.
Documentation in a PDF that you can’t access until you have a sale calls.
Documentation on just a website.
No documentation.
Random forums I have to sign up for that are separate from the help desk sign up that are separate from the actual services signup.
Not be able to search across others issues and to solve problems without needing to ask.
Using HN to get assistance.
Using Twitter to get assistance.
Hoping my email doesn’t get lost or stuck in spam either way.
Having notifications so I can respond.
Not having to sit on some website in some chat window.
Not having to use some crappy web form that won’t take my screenshot because it’s 2MB instead of only being at most 1MB.
Not being able to add attachments at all.
Being able to have a real time conversation with someone.
Still having a search function.
Have something that works well on mobile and desktop. (Oh, but websites work well on both… OH no they don’t have to. People can easily screw that up and make websites that work horribly on difference devices).
All of these things can be solved, but they aren’t.
And keep in mind, the context of the discussion here isn’t documentation that ONLY exists on Discord. Rather, documentation that exists on web AND also stuff that exists on Discord. So, stuff that has yet to make it to the website.
> These are, off the top of my head, the things Discord solves: 1) Documentation that requires you to sign up to yet another website. 2) Paying for documentation. 3) Documentation in a PDF that you can’t access until you have a sale calls.
Huh?
Who has ever had to log into something to view documentation? Discord seems to be the only example!
Paying for documentation? Same thing, never had to it, pretty sure businesses don't think this is viable in any way.
As for the last one, well, getting you on to a Discord and into their marketing drip feed is a lot cheaper than having a sales call.
MSDN sold a service where they mailed you physical CDs. Once they had the documentation on their website it was all free. (A subscription would get you licenses for QAing on different versions of Windows / additional other stuff, but the help files were free)
It's certainly less common now, but prior to 2015 it was common for "legacy" vendors (y'know... the paranoid and posessive types, like ProgressDB...) - or just those embarassed about the state of their products compared to the rest of the industry: they'll hide their KB articles, bug-reports and workarounds, and more besides) behind a registration-wall, or even worse: only grant you access if you have a current support contract with them.
At least their SQL documentation is public - I remember (at least a decade ago) that only Postgres, MySQL, and MSSQL made their documentation public, while info on IBM DB2 and Oracle was scarce.
The whole point is that they don't have to answer. They hope someone else from the community will before they get to it.
It is the evolution of the mailing list then forum style "support". Make a forum, let people ask question and answer them themselves. Ideally don't participate in the communication at all yourself. Win!
We've had great luck at $CURJOB with forum software. Definitely have had folks do their own research and mention forum posts when they ask questions of our support staff. We even have an internal slack channel where we capture questions that have been asked on other media (including private slack channels and github issues) and generalize it to post on the forums. This helps future questioners.
Forums attract SEO traffic, but are more middle of the evaluation funnel, when people want an answer to a question about a specific piece of software.
I think chat is great for companies, just not communities.
> Yes yes, I know that many won't even touch the help portal/documentation and ask questions regardless
It's far easier to drop a link to answer a common q and let the person read it than to engage in the back and forth to answer fully answer a question. You can always have the back and forth if the doc doesn't meet their needs.
We were considering using https://www.linen.dev/ for our own slack group for this reason - it surfaces information from these chat groups and makes it available via search. Anyone here tried them out?
There's always going to be people who don't read your documentation and just post on your form but I think it's a pretty big fallacy to say for that reason it's useless for us to create and publish good documentation. You'd need data on customers that look through your documentation and never post to make that assertion.
One of the reasons everyone hates writing documentation is precisely because nobody reads them.
So this becomes a question of whether the time "wasted" writing documentation is cheaper than wasting time answering the same question again and again and again and again and again.
If nobody reads documentation, it means they don't trust it.
Trust is something that documentation for a project has to earn over time.
People will assume the documentation is incomplete and out-of-date, because that's the default for most things.
If it's comprehensive and stays up-to-date with new changes, the project community will eventually come to realize they and start trusting it. But it takes time to build up that track record!
I don't think that they don't trust documentation. I think that they don't want to invest half or a full day reading the docs and learning every facet of the tool. They are in hurry and if they can find the right answer, discord, ChatGPT, whatever, that would do.
I read all the Unix man page of every command line program I used but there were only a few of them. There are a zillion of tools now, I can't spend days reading their docs: I won't be able to deliver to my customers and get paid. Googling how to do X magically works well enough.
Discord is the very last resort, only if desperate. I tend to keep very far away from tools that have discord as their primary documentation. There are always alternatives.
I think we also tend to teach people to not read documentation (or spend time learning anything, really).
Maybe there is some kind of negative reinforcement, too. The way it feels to me is: "I won't write documentation, because users don't read it -> Oh great, I will use ChatGPT to support my users -> The users don't know how to read documentation (or anything other than a 500-letters answer to a chat question) because they do everything with ChatGPT-like prompts -> I won't write documentation, because users don't read it".
Same for many things: most people tend to complain about CMake, but almost every time, I quickly realize that they don't know how to use CMake. Either they complain about it and never used it, or they complain and use it wrong. Therefore many devs try to build alternatives that will solve that problem by "being better than CMake". Turns out I have seen Meson projects that were a big mess, it's not just a CMake thing. On the other hand, people who learn how to use Autotool/CMake/Meson usually manage to make it quite maintainable.
Here the negative reinforcement would be: "People don't learn how to use the tools properly -> They make a mess -> They complain about the tool -> Someone makes a "better tool" -> People don't learn the new tool and make a mess -> repeat.
I truly believe that we could solve many problems by teaching people how to learn, instead of building technology that helps them being productive without learning.
CMake has a bit of a documentation problem, though. Firstly because the tool really was pretty bad at the start and the correct way to use it is the new way, but all the examples people run into in the wild are generally using it wrong, and this becomes self-perpetuating. The second issue is that the main documentation is actually really light on examples, it's just a fairly dry (and not always helpful) description of each part of it. I know there's some pretty good books but that isn't the kind of resource a lot of people are going to use when learning a tool, especially a tool they regard as secondary to their actual goal.
I totally agree that copy-pasting examples from random websites is a bad idea, because there is a very high likelihood that those examples use it wrong.
Regarding the CMake documentation, though, I have been relying on it forever (that's pretty much how I learned CMake), and I personally find it pretty good. That is where I believe there may be some kind of cultural change: I am fine reading the manual (`$ man <command>`) and RFCs and documentation like the CMake one. It feels like "the modern way" is to find an example that does what you need and mimic it (hence the success of stuff like Copilot).
I just feel like my way is more powerful: I can both leverage official documentation (and RFCs, etc) and examples, and I can actually use them together (e.g. read the example, see new stuff there, and go read the official docs about those new things). IMHO, only being able to rely on examples that do almost exactly what one needs is a bit of a loss; people should learn to read actual manuals.
People read the documentation and fails to understand it. Writing good clear documentation that successfully guides your users or customers to gain the most value from your product is incredibly hard.
It's fine to have Discord, or something similar, for when you users come to you with a problem, but then you need to consider if you have to go back at update the documentation. Early in my career hanging out on mailinglists was much more popular, frequently you'd ask a question and the maintainers of whatever software you where using would take the answer and put them into the regular FAQ or documentation. Now we replaced Discord with mailinglists and that might be sensible, the feedback loop just should not be excluded. Discord is terrible place to store knowledge.
If it's hard to write documentation that people will comprehend, doesn't that make it equally hard to write near real-time chat messages that people will understand?
even if people ask the same question rather than looking for docs, it's still a huge timesaver to direct them to the documentation rather than re-explaining from scratch everytime. Plus, after having been shown the docs they _might_ now be aware that they exist and self-serve the next time
Plus it's an opportunity to fix the documentation. You will figure out quickly if a section of it is too confusing. It would also help you to realize if it's not easily discoverable.
Most servers have a bot that people use to store and retrieve common answers so contributors don't have to type it out every time.
Now you could be like clearly that should just be in the web documentation but people still show up and ask even when it is and RTFM isn't exactly nice.
I guess that's true. I also guess one should consider the fact that you could (as long as things don't change) "waste" your time writing the documentation once, and saved time accumulates, while "saving" your time today not writing documentation will accumulate time spent on answering questions over and over.
Saved time today VS saved time tomorrow, the constant question for startups :)
I find this prevalent attitude actually harmful. It is kinda weird thing to think that the tools we use should not need any learning or training, that anyone should just be able to pick them up and be productive.
Of course I understand it is reflective of the current situation where naturally it is not worth seeking expertise when software gets at minumum a redesign every six months if not thrown out completely. But I'd really question is that actually good situation to be in?
Instead of having information available publicly that can be found via Google or browsing a help portal/documentation website, they want everyone to drop into a chat room and ask a question that most likely already was answered before?
It just adds further work for yourself as well. Yes yes, I know that many won't even touch the help portal/documentation and ask questions regardless, but even if 10% could be helped by self-serve support, wouldn't it be worth it to keep something like that up to date instead?