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

Case in point: Arch Wiki

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.

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.

1. Of course people read it.

2. People read the docs when you send them a link to the relevant doc page. Having docs makes your chat support a matter of linking to the right page.

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 :)

If nobody reads the documentation, that's an indication of success, not failure.

It means you've done a good job with the product and people don't need help to use it.

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?

Yes, but don't confuse cause and effect.

That is one of the explanations but you should not dismiss the others.

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?

Yes and no, but at least they'll be able to provide real-time feedback and you can tailor your response to they specific situation.

That is survivorship bias. You hear only from the customers who don't read it.

(I like writing documentation.)

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

...just something I've noticed.

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.

> Paying for documentation? Same thing, never had to it, pretty sure businesses don't think this is viable in any way.

Very normal when working with ICs.

> Paying for documentation? Same thing, never had to it

It was once very common. Microsoft had a "developers club" that basically sold access to their APIs docs.

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)

I used to spend a nickel or two on O'Reilly books, too. Those were effectively "the manual" for a lot of things, once upon a time.

What's wrong with documentation on a website?

The complaint was about having to sign up to (register for) yet-another website.

Which site requires you to sign up in order to read documentation?

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.

Oracle requires you to login to get access to most support documents now.

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.

RedHat has traditionally.

Right. This is actually what I, and I think most people, actually want.

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.

People are just going to post their question on your forum anyway, even if it's been answered a hundred times.

And at least with discord it's easy to source answers from your community instead of paying developers to handle support.

You don't see the majority of people that do not do this, because they never interact with you in any way.

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.

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.

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.

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.

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.

Search "python __init__" (sans quotes)

The the first page of results are from, in order:

    mygreatlearning.com
    udacity.com
    geeksforgeeks.org
    stackoverflow.com
    w3schools.com
    micropyramid.com
    edureka.co
    pythonmorsels.com
    tutorialspoint.com
    pythontutorial.net

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)

Surprising, the same search on duckduckgo gives me:

  www.w3schools.com  
  stackoverflow.com  
  docs.python.org

and a sidebar quoting the 2nd result which is the top voted answer to: "What is __init__.py for" on Stackoverflow.

Google is in a sad state it seems.

Google has a vested interest in you going to websites that serve their ads.

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?

[0]: https://docs.python.org/3/tutorial/classes.html

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.

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

geeksforgeeks.org is really dark pattern-y, and has been extremely high ranking for python related questions that seemed to come out of nowhere.

>The ability to talk directly to a real human is really powerful

In a fresh and new project. But how will it look in 5 years when the user numbers are smaller because of other new projects?

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.

There were many times when I would have been lost without the Internet Archive. And more than once it was because of discontinued platforms on MS.

Knowledge in forums or now Discord has a shorter half-life until it's gone completely.

That's sad.

I suspect they've figured out that whole search engine business model thing has been deprecated for months in its current form.

Mostly due to Google being ran internally akin to the Soviet union

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

https://www.thetimes.co.uk/article/epstein-knew-dirty-secret... – 2019

https://www.cnbc.com/2023/05/04/google-co-founder-larry-page... – May 2023

https://en.wikipedia.org/wiki/Larry_Page

> On December 3, 2019, Larry Page announced that he would step down from the position of Alphabet CEO and be replaced by Google CEO Sundar Pichai.

Nobody is writing SEO blogspam for your support problems.

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

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.

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!

Here we all are pretending like there aren’t groups that expect people to look for support on an IRC channel.

This isn’t some new degradation today’s youth have inflicted upon us. Discord is just the new IRC.

Even worse the “community” in the Discord gets angry and berates you for asking a question!

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?

The platform slack with over 10,000 users uses linen. It’s good. Wonder how long it will last though.