Comment on What self hosting feels like (It's painful, please help 🥲)

ExcessShiv@lemmy.dbzer0.com ⁨3⁩ ⁨months⁩ ago

• SexualPolytope@lemmy.sdf.org ⁨3⁩ ⁨months⁩ ago

  Relevant xkcd

  source

  • wick@lemm.ee ⁨3⁩ ⁨months⁩ ago

    Bold of you to assume I know how to read!

    source
• teft@lemmy.world ⁨3⁩ ⁨months⁩ ago

  This is why Technical Writer is a full time job.

  source

  • Semi_Hemi_Demigod@lemmy.world ⁨3⁩ ⁨months⁩ ago

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

    source

    • AlexWIWA@lemmy.ml ⁨3⁩ ⁨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

      source

      • Semi_Hemi_Demigod@lemmy.world ⁨3⁩ ⁨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.

        source

        • -> View More Comments
    • floofloof@lemmy.ca ⁨3⁩ ⁨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.

      source

      • Semi_Hemi_Demigod@lemmy.world ⁨3⁩ ⁨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.

        source
      • JackbyDev@programming.dev ⁨3⁩ ⁨months⁩ ago

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

        source
    • HK65@sopuli.xyz ⁨3⁩ ⁨months⁩ ago

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

      source

      • Semi_Hemi_Demigod@lemmy.world ⁨3⁩ ⁨months⁩ ago

        If you know your weakness is writing documentation, please hire a technical writer.

        source

        • -> View More Comments
• AlexWIWA@lemmy.ml ⁨3⁩ ⁨months⁩ ago

  “set all environment variables”

  source

  • mesamunefire@lemmy.world ⁨3⁩ ⁨months⁩ ago

    More recently its go to discord for the env…no joke.

    source

    • AlexWIWA@lemmy.ml ⁨3⁩ ⁨months⁩ ago

      My face actually dropped when I read this. I will be so mad if I ever encounter this live.

      source

      • mesamunefire@lemmy.world ⁨3⁩ ⁨months⁩ ago

        It sucks…and seems to be catching on. Ive seen a quite a few on GitHub that are now referencing using it instead of the issue tracker.

        source

        • -> View More Comments
• AstralPath@lemmy.ca ⁨3⁩ ⁨months⁩ ago

  The mistake is the assumption of a certain level of end user knowledge.

  source

  • Semi_Hemi_Demigod@lemmy.world ⁨3⁩ ⁨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.

    source

    • Flax_vert@feddit.uk ⁨3⁩ ⁨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)

      source

      • vividspecter@lemm.ee ⁨3⁩ ⁨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.

        source
  • GBU_28@lemm.ee ⁨3⁩ ⁨months⁩ ago

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

    source
• bl_r@lemmy.dbzer0.com ⁨3⁩ ⁨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

  source
• sugar_in_your_tea@sh.itjust.works ⁨3⁩ ⁨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.

  source

  • cron@feddit.org ⁨3⁩ ⁨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.

    source
  • harsh3466@lemmy.ml ⁨3⁩ ⁨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).

    source

    • mesamunefire@lemmy.world ⁨3⁩ ⁨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.

      source
    • sugar_in_your_tea@sh.itjust.works ⁨3⁩ ⁨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).

      source
• JackbyDev@programming.dev ⁨3⁩ ⁨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.

  source
• hperrin@lemmy.world ⁨3⁩ ⁨months⁩ ago

  I don’t think it’s (just) that. It’s also a different skill set to write documentation that it is to write 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.

  source
• marcos@lemmy.world ⁨3⁩ ⁨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?)

  source