• ExcessShiv@lemmy.dbzer0.com
    link
    fedilink
    English
    arrow-up
    269
    ·
    edit-2
    5 months ago

    Yeah the documentation (if it even exists) of most projects is usually clearly written by people intimately familiar with the project and then never reviewed to make sure it makes sense for people unfamiliar with it. But writing good detailed documentation is also really hard, especially for a specialist because many nontrivial things are trivial to them and they believe what they’re writing is thorough and well explained even though it actually isn’t.

      • Semi-Hemi-Lemmygod@lemmy.world
        link
        fedilink
        English
        arrow-up
        66
        arrow-down
        2
        ·
        5 months ago

        It’s also why the humanities are important. Stemlords who brag about not doing literature classes write terrible documentation.

        • AlexWIWA@lemmy.ml
          link
          fedilink
          English
          arrow-up
          33
          ·
          5 months ago

          My CS major required me to take two upper division English classes and I think they helped me more in my career than my upper division CS classes. People forget that documentation is for ourselves too

          • Semi-Hemi-Lemmygod@lemmy.world
            link
            fedilink
            English
            arrow-up
            13
            ·
            5 months ago

            I’m really thankful that I had a great English teacher in high school, and that my degree required a technical writing class. Being able to write a coherent email got me further in my career than the technical stuff I learned in college.

            • AlexWIWA@lemmy.ml
              link
              fedilink
              English
              arrow-up
              5
              ·
              5 months ago

              I completely agree. Most peer feedbacks that I get mention my documentation. It has helped me so much

        • floofloof@lemmy.ca
          link
          fedilink
          English
          arrow-up
          13
          ·
          5 months ago

          I think this is why the “my code documents itself” attitude appeals, even though it’s almost never enough. Most developers just can’t write, nor do they want to.

          • Semi-Hemi-Lemmygod@lemmy.world
            link
            fedilink
            English
            arrow-up
            6
            ·
            5 months ago

            The problem with “It’s self-documenting” is that there are inevitably questions about what it says, and there’s no additional resources to pull from.

          • JackbyDev@programming.dev
            link
            fedilink
            English
            arrow-up
            1
            ·
            5 months ago

            “my code documents itself” and “no, our CI system doesn’t upload the source jars to Artifactory, why?”

        • ℍ𝕂-𝟞𝟝@sopuli.xyz
          link
          fedilink
          English
          arrow-up
          6
          arrow-down
          3
          ·
          5 months ago

          Maybe, just maybe, people have different strengths and weaknesses and cooperating around our differences is what makes us succeed.

            • ℍ𝕂-𝟞𝟝@sopuli.xyz
              link
              fedilink
              English
              arrow-up
              11
              ·
              5 months ago

              That’s exactly what I’m saying, sorry if it came across somehow askew.

              My point was there is no point in competing over whose job is “better”, we should be working together.

              • vividspecter@lemm.ee
                link
                fedilink
                English
                arrow-up
                5
                ·
                5 months ago

                There is a case to be made that people should be a bit more well rounded in general, and not just find a specific niche.

                So non-technical people should still have a decent familiarity with computers and maybe be able to do some very basic coding. And technical people should spend some time working on their written and verbal communication.

                Because in both cases, it makes people more effective in their roles.

              • Semi-Hemi-Lemmygod@lemmy.world
                link
                fedilink
                English
                arrow-up
                2
                ·
                5 months ago

                Totally agree. And I’d argue that we don’t even need technical writers. Even if all people do is correct grammar and spelling mistakes it would be helpful, let alone actually writing docs. It’s one of the easiest ways non-technical folks can get involved with open source projects.

                • JackbyDev@programming.dev
                  link
                  fedilink
                  English
                  arrow-up
                  2
                  ·
                  5 months ago

                  Every time I get stuck on something confusing I’m a README and figure it out I try to submit a patch that makes it more explicit.

            • GBU_28@lemm.ee
              link
              fedilink
              English
              arrow-up
              1
              arrow-down
              3
              ·
              5 months ago

              If the documentation is sufficient for the intended audience, it’s good enough.

        • Tja@programming.dev
          link
          fedilink
          English
          arrow-up
          1
          arrow-down
          2
          ·
          5 months ago

          Humanities are very important. Robots are not yet capable of flipping burgers!

      • Semi-Hemi-Lemmygod@lemmy.world
        link
        fedilink
        English
        arrow-up
        66
        arrow-down
        3
        ·
        5 months ago

        You have to assume some level of end user knowledge, otherwise every piece of documentation would start with “What a computer does” and “How to turn your computer on.”

        I’ve found the best practice is to list your assumptions at the top of the article with links to more detailed instructions.

        • Flax@feddit.ukOP
          link
          fedilink
          English
          arrow-up
          16
          ·
          5 months ago

          I do agree, manies have I found documentation saying “make a fresh install of Raspbian” as if I’m using the computer for this single issue

          (Disclaimer: I am not running matrix on a Raspberry Pi)

          • vividspecter@lemm.ee
            link
            fedilink
            English
            arrow-up
            6
            ·
            5 months ago

            Another case is listing a huge number of steps to do some task, without acting describing what the end goal for each set of instructions is (common in “how to” guides, and especially ones that involve a GUI).

            This means that less technical users don’t really understand what is going on and are just following steps in a rote way, and it wastes the time of technical users since they probably know how to achieve each goal already.

      • GBU_28@lemm.ee
        link
        fedilink
        English
        arrow-up
        2
        arrow-down
        6
        ·
        5 months ago

        Why’s that a mistake? Not everything is built for a novice

        • Tja@programming.dev
          link
          fedilink
          English
          arrow-up
          2
          arrow-down
          3
          ·
          5 months ago

          I agree with this. When I publish my code, it is documented for someone in my field with around my level of knowledge. I assume you know DNS, I assume you know what a vector is, I assume you know what a dht is, I assume you know what O(log n) is.

          I’m not writing a CS50 course, I’m helping you use the code I wrote.

          Might be different for software like libre office which is supposed to be used by anyone, but most software on earth is built with other developers in mind.

    • bl_r@lemmy.dbzer0.com
      link
      fedilink
      English
      arrow-up
      24
      ·
      5 months ago

      This is why I did a “walkthrough test” when I had to write documentation on this sort of thing. I’m a terrible technical writer, so this shit is necessary for me.

      I grabbed my friend who knows enough about computers to attempt this, but not enough about infrastructure to automatically know what I meant when I was too vague.

      Took two revisions, but the final document was way easier to follow at the end

    • JackbyDev@programming.dev
      link
      fedilink
      English
      arrow-up
      12
      ·
      5 months ago

      Reminds me of the time I asked a question about a Magic: The Gathering card tomy local game store’s Facebook page. The card was Sublime Archangel. I asked what happened if it gave a creature Exalted that already had one. Someone sarcastically replied that it already says it on the card. I was a new player, how was I supposed to parse the phrase “If a creature has multiple instances of exalted, each triggers separately”? For all I knew that could mean that they didn’t stack because they would need to trigger together. I didn’t have the vocabulary to understand those things.

      I try to remember this when explaining what I might believe are simple concepts to people because that person really upset me.

    • sugar_in_your_tea@sh.itjust.works
      link
      fedilink
      English
      arrow-up
      9
      ·
      5 months ago

      That’s why blog posts rock. Most popular projects will have a dozen blog posts for different configurations. For example, when looking to set up NextCloud, I found docs for almost all combinations of the following:

      • Apache and Nginx configuration
      • running through Docker or directly on the host
      • MariaDB and Postgres configs (and SQLite, with proper disclaimers)
      • Collabora and OnlyOffice config

      It does take some knowledge of each of the above if you need one of the few configs that’s not available on a blog post, and some of the posts are outdated, but with a bit of searching almost everything is documented by someone on the internet.

      This shouldn’t be necessary (official docs should be more comprehensive), but at least it’s available.

      • cron@feddit.org
        link
        fedilink
        English
        arrow-up
        15
        ·
        5 months ago

        I’d rather have a great documentation than five different blog posts, where some of them might be outdated, wrong or insecure (and you only find out later).

        But yes, they are helpful and easily available for popular software.

      • harsh3466@lemmy.ml
        link
        fedilink
        English
        arrow-up
        5
        ·
        5 months ago

        Okay, please point me to the blog posts that helped you with collabora/onlyoffice. Thanks have NEVER been able to get that to work with my nextcloud (currently using the Docker AIO).

        • mesamune@lemmy.world
          link
          fedilink
          English
          arrow-up
          2
          ·
          edit-2
          5 months ago

          Same with me. I played around with the setup a few times on my local machines. It took quite a bit to get it set up, then I saw an error after a couple of days and gave up. Its easier to just pull down the file and run it locally than use collabora.

        • sugar_in_your_tea@sh.itjust.works
          link
          fedilink
          English
          arrow-up
          1
          ·
          5 months ago

          I’m not at the same computer I used to look it up, so I don’t have my search history, but I think this one was pretty decent. I don’t use Traefik, but the rest describes the important bits w/ docker compose. I don’t know much about the AIO image though (I used separate images).

    • marcos@lemmy.world
      link
      fedilink
      English
      arrow-up
      4
      ·
      5 months ago

      That’s just sloppiness.

      The information that familiarity gives you is “WTF does this field means”, and it’s the only thing that’s actually there. How you get a value and how a value is formatted are things no amount of expertise will save you from having to tell the computer, and thus you can’t just forget about.

      (And let me guess, the software recommended install is a docker image?)

    • hperrin@lemmy.world
      link
      fedilink
      English
      arrow-up
      2
      ·
      edit-2
      5 months ago

      I don’t think it’s (just) that. It’s also a different skill set to write documentation than code, and generally in these kind of open source projects, the people who write the code end up writing the documentation. Even in some commercial projects, the engineers end up writing the docs, because the higher ups don’t see that they’re different skill sets.

    • Presi300@lemmy.world
      link
      fedilink
      English
      arrow-up
      2
      ·
      5 months ago

      100% Agree, it feels like most documentation is written in a way that expects you to already know what it’s talking about… When it’s the documentation’s job to teach me about it.