• ExcessShiv@lemmy.dbzer0.com
    link
    fedilink
    English
    arrow-up
    269
    ·
    edit-2
    2 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
        ·
        2 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
          ·
          2 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
            ·
            2 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
              ·
              2 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
          ·
          2 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
            ·
            2 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
            ·
            2 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
          ·
          2 months ago

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