A place to share alternatives to popular online services that can be self-hosted without giving up privacy or locking you into a service you don't control.
Rules:
Be civil: we're here to support and learn from one another. Insults won't be tolerated. Flame wars are frowned upon.
No spam posting.
Posts have to be centered around self-hosting. There are other communities for discussing hardware or home computing. If it's not obvious why your post topic revolves around selfhosting, please include details to make it clear.
Don't duplicate the full text of your blog or github here. Just post the link for folks to click.
Submission headline should match the article title (donβt cherry-pick information from the title to fit your agenda).
No trolling.
Resources:
Any issues on the community? Report it using the report flag.
Questions? DM the mods!
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.
This is why Technical Writer is a full time job.
It's also why the humanities are important. Stemlords who brag about not doing literature classes write terrible documentation.
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
Maybe, just maybe, people have different strengths and weaknesses and cooperating around our differences is what makes us succeed.
"set all environment variables"
More recently its go to discord for the env....no joke.
My face actually dropped when I read this. I will be so mad if I ever encounter this live.
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.
That is so depressing. Literally a markdown file in the repo would be a better issue tracker.
Donβt forget to run your shell over Discord!
This is cursed, but also cool. Hijack another platform for your authentication
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
The mistake is the assumption of a certain level of end user knowledge.
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.
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:
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.
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).
I write technical documentation and training materials as part of my job, and the state of most open source documentation makes me want to stab people with an ice pick.
You're doing God's work!
Over my career, it's sad to see how the technical communications groups are the first to get cut because "developers should document their own code". No, most can't. Also, the lack of good documentation leads to churn in other areas. It's difficult to measure it, but for those in the know, it's painfully obvious.
Do you have any tips for writing professional documentation? I want to do some for my workplace but it's hard to know where to start, how to arrange it, etc
Do you have some reading recommendations on how to write good documentation, e.g. readmes for end users?
Yes. Here: "1.You aren't writing an SOP for smart or even capable people., every. Single. Person. Needs their hand held all the way through every step regardless of technical skill. "
"2.if you didnt state it needed to be done in the SOP, it will not be done when the end user follows the SOP"
"3.MAKE someone else run through your SOP without you being involved. If they can successfully achieve what they needed using your SOP > congrats. If not > fix the errors that brought you to this mess."
"4. Everyone is fucking stupid, be clear, and verbose." We're talking about where the start menu is, clicking on the "OK" for prompts, how to spell and type things out.
Change my given values per SOP and what it's for. But those are my main tenants.
In elemental school we had to write instructions on how to make a pb&j sandwich. The teacher then acted out your instructions literally, without adding or removing a step. I don't think there was a single sandwich made that day.
Excellent notes. If I could add anything it would be on number 4 -- just. add. imagery. For the love of your chosen deity, learn the shortcut for a screenshot on your OS. Use it like it's astro glide and you're trying to get a Cadillac into a dog house.
The little red circles or arrows you add in your chosen editing software will do more to convey a point than writing a paragraph on how to get to the right menu.
This reminds me of when I sent someone a program in a zip folder. Windows now opens zip folders by default, and it looks just like any other folder.
So of course they opened the zip and double clicked the exe, but everyone knows you can't open an exe inside a zip folder (at least, if the exe depends on the folders and files around it). If you try to, windows will extract the exe into a temp space, but leave all the dependencies behind. So the exe promptly crashes.
I didn't think I needed to specify "you need to extract the contents of the zip folder first, then run the exe." It feels like saying "you need to take the blender out of the box before you can use it. And not just the _base _ of the blender, you have to take out all the parts."
Some things just feel so much like second nature that we forget.
In many ways, the silky-smooth convenience offered by modern computer software makes everything much harder to learn about and understand. For anyone that used zip files before this Windows feature, the problem is obvious - but for younger people it's not obvious at all. Heck, a lot of people can't even tell whether or not a file is locally on their computer - let alone whether it is compressed in some other file.
I totally and completely blame Microsoft for this. They do so many other ridiculous things in the name of not confusing the average tech illiterate user.
Clicking a Zip file and having it transparently open and treating it like a regular folder when it is not. This. THIS is borderline criminal.
Step one: use Dendrite instead.
Step two: come back and help me set up my Dendrite instance, it's definitely not easier.
Here's some more of the owl, the official docs: https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#registration_shared_secret
So add this to your matrix config:
registration_shared_secret:
I'm guessing this string can be whatever you want it to be.
But yeah, I agree in general, some of the docs can be pretty opaque. For example, I wanted to configure NextCloud w/ Collabora in Docker, and I kept getting errors when trying to do what a few sites recommended. I ended up figuring it out, but only through trial and error. I'm going to go through the same pain this weekend when I try out ownCloud Infinite Scale up and running to compare.
Protip: Use Conduit instead of Synapse. It's significantly lighter than Synapse, easier to run, and I guess you can be a cool kid by running something written in Rust. The documentation is even worse though :/ https://conduit.rs/
Acronyms, initialisms, abbreviations, contractions, and other phrases which expand to something larger, that I've seen in this thread:
| Fewer Letters | More Letters |
|---|---|
| DNS | Domain Name Service/System |
| HTTP | Hypertext Transfer Protocol, the Web |
| IP | Internet Protocol |
| SMTP | Simple Mail Transfer Protocol |
| ZFS | Solaris/Linux filesystem focusing on data integrity |
5 acronyms in this thread; the most compressed thread commented on today has 3 acronyms.
[Thread #905 for this sub, first seen 3rd Aug 2024, 13:15] [FAQ] [Full list] [Contact] [Source code]
Honestly, as a newbie to Linux I think the ratio of well documented processes vs. "draw the rest of the fucking owl" is too damn high.
The rule seems to be that CLI familiarity is treated as though its self-evident. The exception is a ground-up documented process with no assumptions of end user knowledge.
If that could be resolved I think it would make the Linux desktop much more appealing to wider demographics.
That said, I'm proud to say that I've migrated my entire home studio over to linux and have not nuked my system yet. Yet... Fortunately I have backups set up.
Linux on the desktop almost never needs CLI interaction though. Maybe you'll need to copy/paste a command from the internet to fix some sketchy hardware, but almost everything works OOTB these days.
However, self-hosting isn't a desktop Linux thing, it's a server Linux thing. You can host it on your desktop, but as soon as you do anything remotely server-related, CLI familiarity is pretty much essential.
That depends on your use case for desktop linux of course. For me, yabridge is the tool I needed to run VSTs on Linux. Its CLI only as far as I know.
Don't get me wrong; I'm not afraid of the CLI. Its just some tools are assuming the end user is a server admin or someone with deeper than the upper crust knowledge of how Linux works.
yabridge
Ah, that's a pretty niche use-case. But yeah, the deeper you go, the more you'll have to rely on the CLI.
Matrix and its implementations like Synapse have a very intimidating architecture (I'd go as far as to call most of the implementations somewhat overengineered) and the documentation ranges from inconsistent to horrific. I ran into this particular situation myself, Fortunately this particular step you're overthinking it. You can use any random string you want. It doesn't even have to be random, just as long as what you put in the config file matches. It's basically just a temporary admin password.
Matrix was by far the worst thing I've ever tried to self-host. It's a hot mess. Good luck, I think you're close to the finish line.
The dankest depths of archlinux wiki. Written by a guy so far gone, so war harden by reading through source code and poorly written technical documentation, ancient forums, leaving no stone unturned. A task so twisted it drives most men crazy.
1% of arch users will ever need this wiki and few have gone through this Herculean task. For them, the first draft is enough, it's all you can ask of a mind so twisted and broken. Alas it's as unreadable as the source code and as hard to understand as the forum post from 2009.
I mean... Bad documentation isn't specific to selfhosting.
this meme got so much funnier after I realized it was synapse/matrix
