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
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.
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.
"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.
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.
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)
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
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.
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.
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.
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.
Don't forget the situations where you find a good blog post or article that you can actually follow along until halfway through you get an error that the documentation doesn't address. So you do some research and find out that they updated the commands for one of the dependency apps, so you try to piece together the updated documents with the original post, until something else breaks and you just end up giving up out of frustration.
CLI familiarity is fine. CD, Nano, mkdir, rm. I am proficient with that. But I am not necessarily proficient with Docker (went with it because it worked nicely for another thing which was well documented and very straight forward). It's just I'm trying to self host stuff. Some things like Wordpress and Immich are straightforward. Some things aren't like Matrix and Mastodon. Lemmy is also notoriously bad.
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 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.
I'll see about digging up recommendations if I can, but I'm on my phone right now.
My biggest single piece of advice would be this: Understand that your reader does not share your context.
What this means is that you have to question your assumptions. Ask yourself, is this something everyone knows, or something only I know? Is this something that's an accepted standard, or is it simply my personal default? If it is an accepted standard, how widely can I assume that accepted standard is known?
A really common example of this in self-hosting is poorly documented Docker instructions. A lot of projects suffer from either a lack of instructions for Docker deployment, because they assume that anyone deploying the project has spent 200 hours learning the specifics of chroot and namespaces and can build their own OCI runtime from scratch, or needlessly precise Docker instructions built around one hyper-specific deployment method that completely break when you try to use them in a slightly different context.
A particularly important element of this is explaining the choices you're making as you make them. For example a lot of self-hosted projects will include a compose file, but will refuse to in any way discuss what elements are required, and what elements are customisable. Someone who knows enough about Docker, and has lots of other detailed knowledge about the Linux file system, networking, etc, can generally puzzle it out for themselves, but most people aren't going to be coming in with that kind of knowledge. The problem is that programmers do have that knowledge, and as the Xkcd comic says, even when they try to compensate for it they still vastly overestimate how much everyone else knows.
OK, I said I'd try for examples later, but while writing this one did come to mind. Haugene's transmission-openvpn container implementation has absolutely incredible documentation. Like, this is top tier, absolutely how to do it; https://haugene.github.io/docker-transmission-openvpn/
Starts off with a section that every doc should include; what this does and how it does it. Then goes into specific steps, with, wonder of wonders, notes on what assumptions they've made and what things you might want to change. And then, most importantly, detailed instructions on every single configuration option, what it does, and how to set it correctly, including a written example for every single option. Absolutely beautiful. Making docs like this is more work, for sure, but it makes your project - even something like this that's just implementing other people's apps in a container - a thousand times more usable.
(I've focused on docker in all my examples here, but all of this applies to non-containerized apps too)
I used to mock people who make YouTube videos that literally just walk through the documentation. Like bro, get some reading comprehension!
But then when I fumbled with some self hosting tutorials, those YouTube videos were the only thing that made sense, because they're explaining why and how.
Sorry y'all.
Step one: use Dendrite instead.
Step two: come back and help me set up my Dendrite instance, it's definitely not easier.
Step one: email must be much easier, I'll just make an email server instead.
Step two: screw this, I'm writing letters and posting them.
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.
Doesn't Windows give a popup saying "Do you want to extract the folder before running the executable" anymore?
Edit: typo (funning to running)
Am I the only one in this thread that took this as it’s asking for a clear text credential which is a terrible idea?
A temporary one that you're expected to remove as soon as you've created the admin user(s) you need, but yes. It should only be there during initial setup and ideally removed before the server is ever exposed to the internet.
update: It's all working perfectly!
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.
I had very similar experiences with OCIS. Got it all set up following the quick start guide, found extremely odd and unacceptable behaviour with storage space ballooning, start troubleshooting and find “oh you had to do this, this and this manually, it’s in the docs” It is in the docs, but never referenced by any other part of the docs. Because why would you mention the thing that the admin must manually set up in 100% of installs in your setup guide?
Anyway I’ve become that guy ranting on the internet that I don’t want to be. So just so you don’t suffer as much as I did; you have to create scheduled tasks via cron or your preference of scheduler to clean your uploads folder and data blobs. This also did not fix my specific issue and I ended up giving up on OCIS and sticking to Nextcloud.
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.
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/
this meme got so much funnier after I realized it was synapse/matrix
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!
