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.
I still have to sort out having a different server name to the access name so I can use the domain as well. Do I just put a field into the config like the rest? Can it go anywhere?
Matrix seemed interesting right until I got to self hosting it. Then, getting to know it from up close, and the absolute trainwreck that the protocol is, made me love XMPP. Matrix has no excuse for being so messy and fragile at this point. You do you, but I decided that it isnāt worth my sysadmin time (especially when something like ejabberd is practically fire and forget).
funnily thereās anā¦ ansible i think? project that makes selfhosting synapse easy as fuck, you basically just go āansible deploy synapseā or whatever the syntax is and it does almost everything for you.
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.
Iām going to run both in parallel for a month or so before trying to get my SO to use it so I can better estimate the WAF. So far, NextCloud is good enough, but itās kinda slow (and I have Redis configured) despite being on pretty beefy hardware (Ryzen 1700 w/ 16GB RAM). I really hate PHP, so Iād prefer a project I can contribute to if needed. I worked w/ Go for almost 10 years, so OCIS would be a natural fit, but Iād still contribute patches for PHP if that really was the best tool for the job. But Iām not going to get involved unless the project already does what I need (my contributions would be for smaller bug fixes).
But yeah, the OCIS docs look kinda mediocre from the little Iāve read of them. But at least I donāt need to mess w/ PHP config most likely and can hopefully just forward HTTP requests to it.
The move from php to go and the slowness of NC is what attracted me to the project. But Iām going to wait a bit longer until weāre flush with 3rd party setup guides cause I simply do not have the time to wade through their docs.
Yup, thatās why I started w/ NextCloud. It was painful enough getting Collabora working with NC, so hopefully OCIS is easier now that I know my Collabora setup at least works.
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.
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.
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.
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.
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.
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ā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).
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.
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.
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.
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.
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.
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.
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.
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?)
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.
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.
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.