Improving the installation docs and config.sample.yaml

[jaller94]

• In the docs, be explicit which config fields need to be changed.
• Simplify config.sample.yaml
  • Move homeserver, db and matrix_admin_room to the top. They will likely get changed by an admin.
  • Comment out tls and oauth2. They are optional, and tls prevents the server from starting in the former state.
• Rename the page "Workspace Sync" to the more common name "Team Sync"

[anoadragon453]

A mostly stylistic review from someone unfamiliar with the project. Will likely need another review from someone about the correctness of everything.

[anoadragon453]

Could you either:

• Remove the space before commented out option names or
• Put a newline between options

as I find it hard to notice that there are multiple options in this comment blob.

[jaller94]

It's a bit easier with syntax highlighting.
All my code editors put a space after the comment character, so it's very annoying to maintain comments without the space.
Adding newlines makes the file length significantly longer and less readable when introducing a newline consistently between all properties.

[anoadragon453]

I disagree that:

  # The domain name of your homeserver
  server_name: my.server.here

  # The URL which the bridge server can reach the homeserver on.
  # You can use localhost so long as the bridge and homeserver are
  # hosted on the same machine
  # 8008 is assumed to be the port the homeserver listens on
  url: http://localhost:8008

  # The public facing url for media on your homeserver.
  # This is usually the public url of your homeserver.
  # Optional, will use `url` by default.
  # media_url: "http://my.server.here"

  # Optional. The maximum size of a uploaded file to Matrix in bytes. No limit by default
  # max_upload_size: 104857600

  # Optional. Used to specify the port of the appservice in the config, rather than the cli.
  # If this is defined, it will **override** the port given in the process arguments.
  # appservice_port: 9999

is less readable than:

  # The domain name of your homeserver
  server_name: my.server.here
  # The URL which the bridge server can reach the homeserver on.
  # You can use localhost so long as the bridge and homeserver are
  # hosted on the same machine
  # 8008 is assumed to be the port the homeserver listens on
  url: http://localhost:8008
  # The public facing url for media on your homeserver.
  # This is usually the public url of your homeserver.
  # Optional, will use `url` by default.
  # media_url: "http://my.server.here"
  # Optional. The maximum size of a uploaded file to Matrix in bytes. No limit by default
  # max_upload_size: 104857600
  # Optional. Used to specify the port of the appservice in the config, rather than the cli.
  # If this is defined, it will **override** the port given in the process arguments.
  # appservice_port: 9999

All my code editors put a space after the comment character, so it's very annoying to maintain comments without the space.

I have to ask how often you add new options to this config file for hitting backspace once to be a major inconvenience.

[anoadragon453]

These are just suggestions that we apply to synapse's config, which while monumentally longer, we don't receive complaints about the length.

If you don't want to apply them though, that's fine - it's only a suggestion.

[anoadragon453]

Looks good other than the readability responses I left above.

[jaller94]

@Half-Shot Explicitly setting config.db.engine to "nedb" never worked, did it?

Also, do you agree with this change to format the sample file like Synapses sample with a lot more spacing for comments? Anoa suggested it and I like it.

[Half-Shot]

Also, do you agree with this change to format the sample file like Synapses sample with a lot more spacing for comments? Anoa suggested it and I like it.

Spacing never hurt anyone, I'm all for it.

Explicitly setting config.db.engine to "nedb" never worked, did it?

It should do?

[jaller94]

The comments in the sample config and the schema list "nedb" as a valid value.

[Half-Shot]

I'm generally happy that this is an improvement, thank you for taking this on!

[Half-Shot]

We've since added new options to the config, can you double check we have all of them included in this file?

[jaller94]

I checked again that all values are also present in the new file. Some optional values have been commented out.

[Half-Shot]

I don't see anything in there for the encryption stuff?