• OneCardboardBox@lemmy.sdf.org
    link
    fedilink
    English
    arrow-up
    242
    ·
    10 months ago

    Firstly, discord is entirely the wrong medium for documentation.

    Secondly, documentation should be at least as accessible as the code. That is to say, if I can view the code without creating an account for some service, then I should also be able to read the documentation too.

    • dustyData@lemmy.world
      link
      fedilink
      arrow-up
      53
      ·
      10 months ago

      Documentation is bad enough. But it’s worse when that’s the only channel to get support. I once read a project maintainer boast that they never read the bug reports and issues on github and if anyone had a bug to just chat him up discord. I mean, dude, no wonder nobody uses your software or takes it seriously. Much less want to collaborate on the development.

      • shadow@lemmy.sdf.org
        link
        fedilink
        arrow-up
        17
        ·
        10 months ago

        I can’t understand why someone would want to do that. Maybe it’s my help desk and IT upbringing, but for the few software tools and things I’ve made, if you chat me without filing a bug/issue on GitHub, I’m not gonna help you.

        • Baku@aussie.zone
          link
          fedilink
          English
          arrow-up
          6
          ·
          10 months ago

          To play devil’s advocate here: sometimes there are genuine reasons to try and request support before making an issue. I’m not particularly smart, nor too techy. If something isn’t working, I’m just going to assume I’m an idiot and I’ve messed something up. If I can’t figure out how to make it work, my first post of call will be trying to find a community related to whatever isn’t working, or on smaller projects I might try and reach out to the Dev. Opening an issue always feels like a “hey, your program isn’t doing what it’s meant to do, here’s what’s wrong with it, please fix it” and not “I think I’ve fucked something up, can you please help?”

          I suppose it depends what you’re developing though.

            • shadow@lemmy.sdf.org
              link
              fedilink
              arrow-up
              9
              ·
              10 months ago

              Yep, and if it becomes a frequent request, add clarification to the readme / wiki / documentation.

              Also, if you push folks towards issues, then they become indexable by search engines! So even if you have a solved problem you can at least find that… Discord? It’s a black hole.

            • JustEnoughDucks@feddit.nl
              link
              fedilink
              arrow-up
              5
              ·
              10 months ago

              And then get it insta-closed withing 20 minutes saying that “this is a problem with your setup, not the software” even when “my setup” was literally setting up their project using their documentation (docker compose files).

              That is how developers treat people with questions that they deem “stupid.”

              It turns out their documentation was wrong and some environment variable that they said was optional, was not actually optional and the service would go into a reboot loop without it. I figured that out no thanks to the devs.

              • crispy_kilt@feddit.de
                link
                fedilink
                arrow-up
                1
                ·
                edit-2
                10 months ago

                Update your issue with a pull request fixing the documentation. When you’re doing things on github, 99.999% of your audience is the general public, not the maintainer, because they will find your issue and solution through search engines.

    • Serinus@lemmy.world
      link
      fedilink
      arrow-up
      14
      ·
      10 months ago

      Agreed. I may not want to mix my discord identity with whatever project I’m looking at. I especially don’t want to mix my personal online identity with my professional identity. I post too much politics for that.