Frustrating experience reading docs for Initial bridge config (With suggestions)

[itsmeehmon]

I just went through the experience of setting up mautrix-whatsapp bridge using the docs, and I found the experience a bit rougher than I would have liked. I've listed some of my pain points and my suggestions as a bulleted list broken up by severity. The pages I interacted with were:
https://docs.mau.fi/bridges/general/initial-config.html
https://docs.mau.fi/bridges/general/double-puppeting.html
https://docs.mau.fi/bridges/general/registering-appservices.html

Gaps which caused actual problems for me enabling the bridge:

• The docs and comments in the example doublepuppet.yaml say that the url is not required except for if your sever is a "non-spec-compliant server". It encounters a problem with that value left blank on element-synapse installed on debian 13. If that is non-spec-compliant, you should be more specific about what would make a server compliant/non-compliant, because I can't think of a more generic/"out of the box" way to be running a matrix server. If that should be considered a spec-compliant server, the text saying it's not necessary should be removed.
• Postgres requires url-encouded passwords and the bridge will fail to start if given unescaped special characters in the db uri. This isn't really on mautrix and I can understand a resistance to writing documentation for postgres, but it will cause the bridge to fail and based on past experiences I believe is likely to be encountered by a non-trivial number of users and so is worth calling out regardless.

Bad practice for Documentation/Little "F you"s to the reader:

In general there seems to be an expectation of familiarity with functionality/configuration not explained in the section currently being read, it reached the point where I was actively frustrated on the Double Puppetting page.

• Never, ever, EVER refer to functionality you have any reason to assume a user might be unfamiliar with as "The Usual Way". The page is linked from "Initial bridge config" as the # 1 recommended next step. You cannot be assuming that level of familiarity with other aspects of the software/configuration.

• Step 3 contains mention to as_token:$TOKEN. This is extremely confusing, because not only is there no context provided for what the heck it does, it uses a different placeholder for the token than the line in the example config. That makes it read as completely unrelated. My initial assumption was that it was referencing a line in a different file not named there. Not good!

Nice-To-Haves/Low Priority:

• SQLite and Postgres are mentioned as options for db config on the Initial Bridge Config. Links out to docs/repos or short code block with example config steps/commands would be nice.
• On the registering appservices page, the Synapse section assumes the existence of a section in the config which is not guaranteed to exist. It would be nice to acknowledge that (ex. append something like "If the section is not present, add it at the end of the file" after "If necessary, copy the registration file somewhere where Synapse can read it. Then add the path to the file under app_service_config_files in Synapse's homeserver.yaml file." )

[tulir]

• Synapse is spec-compliant in that regard and will work fine with a null url. Some older conduit versions weren't, but I'd hope they've fixed it by now
• It's mentioned in the comment now mautrix/go@f80db63

---

• There's only one way to register appservices on each homeserver implementation and the link to the instructions is 6 characters after "the usual way". I guess it could use another word like "the standard way" or something, not sure how that would help at all though
• The part in parenthesis already explains what the as_token:$TOKEN means, but I've added some more words now

---

• The database uri examples are already in the config itself

[itsmeehmon]

Hey, appreciate the prompt response, and the changes you've already implemented!
Some responses to your responses:

Synapse is spec-compliant in that regard and will work fine with a null url. Some older conduit versions weren't, but I'd hope they've fixed it by now

...but a null url did not work at all with Synapse. That's why I brought it up, having it null caused the bridge to error out when I attempted to run it. It would be good to explicitly lay out what's required for spec-compliance, because it's not explained, and clearly is not as simple as "Synapse is compliant" given that my synapse doesn't work with it. It needs further details on what's required. If instead the issue is that a spec-compliant server does not work with a null url, the line saying it does should be removed.

There's only one way to register appservices on each homeserver implementation and the link to the instructions is 6 characters after "the usual way". I guess it could use another word like "the standard way" or something, not sure how that would help at all though

Don't do either! Refer to it as a way "as explained [x]" where [x] is the part of your documentation which explains it, with a link to that part of the documentation. Try to provide some level of context before they click through. People do not sit down and read your documentation from page 1 to the end before doing anything, so it being some number of chapters after is irrelevant. The pages links to other pages which people will follow! Presumably, expecting them to do so is why there links in the pages to begin with.

The Bridge Setup Page which is linked from the github readme as how to install the bridge directs people to the Initial Bridge Config Page for how to set up their config file. That page tells people "Setting up double puppeting is strongly recommended." That link goes to the double-puppeting page. You cannot assume a reader is already familiar with "usual" anything. Do not use terms which skip explanation in favor of hand-waving. People are reading your documentation because they don't already know how it all works.

The part in parenthesis already explains what the as_token:$TOKEN means, but I've added some more words now

It was not a clear explanation. The current page still is somewhat unclear. You should be consistent in placeholders between examples and explanatory text, because again, you cannot assume the reader is going to have the context or understanding you do as an expert. The explaining sentence in the parentheses did not sufficiently make clear that it referred to the text in the example. Having text which does not match that in the example and referencing "as above" does not solve the confusion. Even with the changes it is still somewhat vague. You should reference the actual thing they will be replacing. Ex. in that situation where the example has random string as the placeholder value, something like "Finally, take the random string you set for as_token:... in the example above and set it as the secret value in double_puppet -> secrets". In an ideal world you would do a code snippet or screenshot in the explanatory text and literally have the same text and formatting including color and line numbers to undeniably match the line in the example.

The database uri examples are already in the config itself

I assume this is in reference to the first one of the low priority points? I wasn't trying to say anything about the URIs on that one, I meant it would be nice to literally have a 3-4 line code block with the commands to spin up a new sqlite/psql db. I absolutely appreciate it's outside the scope of how to install/configure the bridge which is the point of the documentation, just nice to not have to pull up another window if you're not managing postgres/sqlite frequently enough that you just remember the commands. I mostly don't use postgres for dbs so I had to go look it up.