WIP: DOCS: Add Userguides to the documentation.

[toby63]

This PR includes User-Guides for Windows, Linux and macOS.
The Content is based on the former content in the README.md and will be extended and updated.

Also included:

• Server Configuration Guide
• Client Configuration Guide
• an overlay_opengl.md file for specifics about the OpenGL overlay

Furthermore links to the Userguides are added to (central) README.md.

Closes: #4623

---

Status:

On hold for now, until Mumble 1.4 is in some kind of feature freeze.
For more info see below.

[toby63]

Note: This is work-in-progress, with large parts (especially regarding configuration) still missing.

Help (especially for the Windows, macOS and overlay parts) and Feedback is appreciated.

Take a look at the Todo-List below.
The files can be found here: https://github.com/toby63/mumble/tree/usage/docs/user-guides
Text Language is markdown.

---

Open Questions:

• Unix: Are the instructions different (from the Linux guide) for Unix/OpenBSD etc.?
• Should we split the Client and Server guides?

---

Todo-List:

Note: Also take a look at the comments in the RAW-versions of the files.

• General:

  • Test (and edit) for Mumble Version 1.4.0
  • Remove all links to the wiki, once the wiki is deleted and link to the new documentation instead
  • Change binary names if [DISCUSS] Server name consolidation: murmur, murmurd, mumble-server #4046 is implemented

• [Help wanted] Overlay overlay_openGL.md: I don't have a clue about the overlay, so someone else has to write something about it.

  • Description: What is it?
    • Screenshot?
  • Activation for different Operating Systems
  • Status: What is working and what not; which Games and programs are working and which not

• [Help wanted] macOS Guide userguide_macos.md: I also don't have a Mac so someone at least needs to give information on that:

  • Workaround for installation is not necessary anymore, but @Krzmbrzl said it would be good to include it anyway.
  • How is installation working? Doubleclick on the file or is it something special?
  • Overlay: Is the seperate overlay installation still working the same way as described?
  • Server: Is the information correct?

• [Help wanted] Windows Guide userguide_windows.md: I don't use Windows either.

  • Questions:

    • How is Mumble started (on windows 10 for example), do you still have a startmenu where you can search for mumble?
    • Is there also a security warning when you install from a file now, like in macOS?
    • Server Installation: Can you simply re-run the installation to install the server afterwards?

  • Todo:

    • Start Mumble Server via console
    • Add more flags, like in the Linux guide?

• [Help wanted] Mobile Guide ?
  - [ ] Android
  - [ ] iOS (though unmaintained)

• Linux Guide (userguide_linux.md):

  • Client: Start from Terminal
  • Server: Instructions to disable auto-start
  • Server: Rework manual start and description of flags
  • Server: Difference between static files (different binary name?)
  • (optional, future) Server: Other static packages?
  • (optional, future) Client: Add Appimage?

• Server Configuration Guide server_config_guide.md:

  • Question: Are there differences between Operating systems?
  • Network Configuration: Static and dynamic IP scenario, Firewall & Ports;
    done, might need some polishing though
  • Main Configuration File (murmur.ini):
    • mention most important options, the rest is linked in the wiki
  • Administration via GUI: Most difficult part, would probably need some pictures to describe it properly; I guess we will only describe it in a very basic way for now.
  • (optional) Security section? Are there methods to increase security?
  • (optional) Troubleshooting section?
  • Additional Stuff (Seperate file/guide?):
    - [ ] gRPC, Web interfaces, grumble: Should imo only be added once it's ready and flawless
    - [ ] Bots

• Client Configuration Guide client_config_guide.md:

  • Question: Are there differences between Operating systems?
  • Audio Wizard? (Start-up wizard)
  • Options Overview + Where to find the options
  • Important Config Options: Topics suggested by Krzmbrzl:
    change theme between Lite and Dark mode, echo cancellation, transmission modes (VAD, PTT, continous), shortcuts
  • Special Parts:
    • Add more options for echo cancel when Experimental Echo Cancellation for MacOS #4694 is merged
  • (optional) Troubleshooting section?
  • (optional) Add Pictures or gifs for better presentation
  • (optional) more config options?

• (optional) More content ideas (seperate files):

  • other mumble clients (pymumble, etc. )

• General tasks, when everything is ready:

  • move this to the website repo
  • Squash and change the commit messages (Use DOCS category in commit description)
  • adjust the central README.md file (link to the Userguides)
  • (optional) Convert the documentation to text and html (for text docs and website)

[Krzmbrzl]

Should we split the Client and Server guides?

As it stands these guides are not too long and thus having them in a single file is fine. If however these are subject to grow (a lot), then it would probably make sense to split them up.

Should I link to the wiki or do we want to aim for replacing the wiki enterily?

In the long-term we do want to get rid of the wiki and move the docs either to our main website or to a GitHub repo (though probably we'd prefer to move it to our website which itself is managed as a repo). Thus everything that links to the wiki now will have to be replaced with links to the new location of the docs eventually but given that we have not moved the docs from the wiki to elsewhere, the wiki currently is the only thing we can link to atm 🤷

Client Configuration: Should I include some more information or just that a wizard will start automatically on first start?

Maybe we could also state that the client can be customized via the settings (and how to get there). Furthermore the most prominent settings could be listed and explained (e.g. change theme between Lite and Dark mode, echo cancellation, transmission modes (VAD, PTT, continous), shortcuts)

Linux: Should I mention how to start Flatpak and Snap packages etc.?

I think a link explaining how these formats have to be used is enough.

Should we rename the "README.md" files to avoid confusion with the main README.md file?

You are referring to docs/user-guides/README.md, right? In that case I'd keep the name as this has the advantage that GitHub will automatically display this file when accessing the respective directory. Therefore it can be used as a TOC. Besides: There shouldn't be any ambiguities as it is in a different directory and contains completely different content 🤔

Server: I would have added something about grumble, gRPC and so on, but it seems none of that is stable yet, correct?

grumble is unmaintained (at least from our side) and gRPC is not stable yet (and thus not even included in all packages). You can mention it as a beta-feature that might or might not be available in any given package though 🤷

---

I have the feeling that the user guides for the different OS will have quite a few things in common. Therefore I am wondering whether it might be better to create a unified guide that then just links to auxiliary files that contain OS specific instructions. This could perhaps be done like this (links not working in this example):

The first step is to install the software on your computer (Windows | Linux | MacOS) and then ...

For the 3 OS we could then have a file each that contains different chapters explaining the OS specific steps and in the main guide we then link to the respective chapter in these auxiliary files as shown above.

[Krzmbrzl]

@davidebeatrici or @Kissaki could one of you write something up for the overlay documentation? I think you are the ones most familiar with this aspect of Mumble

@TerryGeng could you have a look at the macOS-related questions?

I assume that the mac installation files are now signed, so no workaround is necessary anymore?

@toby63 yes the recent installation files are currently signed. I think I would still want the workaround to be documented there in case we do not receive continuous funding for the Apple Account renewal (which then means that we can no longer sign the maxOS builds) ☝️

[Krzmbrzl]

Oh and btw: I would consider all of the commits in this PR so far to belong into the DOCS category. MAINT is usually only used if some auxiliary files (e.g. an issue template) are changed

[toby63]

@Krzmbrzl:

Regarding:

• README.md:
  Ok, you are right, we will keep the naming then.

• Client configuration:

Maybe we could also state that the client can be customized via the settings (and how to get there). Furthermore the most prominent settings could be listed and explained (e.g. change theme between Lite and Dark mode, echo cancellation, transmission modes (VAD, PTT, continous), shortcuts)

I added these as a todo list in the file.
Though I have to say, that it will be some work, so we might add that later.
It would even be useful to add pictures or gifs as well, if someone (including myself) would want to create them 😄.

• Commit titles:

I would consider all of the commits in this PR so far to belong into the DOCS category. MAINT is usually only used if some auxiliary files (e.g. an issue template) are changed

I can change that. I will need to squash this (very much) anyway.
Still you might change your commit guidelines, because the README is mentioned specifically as an example for MAINT.

• Additional features:
  Such as gRPC etc.

You can mention it as a beta-feature that might or might not be available in any given package though shrug

I guess we will leave them in a todo list and add them when these are ready.
I might include links to wiki articles in the meantime, if the wiki articles are good and recent enough.

• Merge all Guides:

I have the feeling that the user guides for the different OS will have quite a few things in common. Therefore I am wondering whether it might be better to create a unified guide that then just links to auxiliary files that contain OS specific instructions. This could perhaps be done like this (links not working in this example):
The first step is to install the software on your computer (Windows | Linux | MacOS) and then ...
For the 3 OS we could then have a file each that contains different chapters explaining the OS specific steps and in the main guide we then link to the respective chapter in these auxiliary files as shown above.

I disagree, I think it is always very confusing and hard to read if (like mostly) everything is combined into one big file.
I think it is best to have these seperate files and instead I link to the common Client Config Guide and Server Config Guide.
This keeps things short and clear imho.

[Krzmbrzl]

Still you might change your commit guidelines, because the README is mentioned specifically as an example for MAINT.

Ah yes this might be confusing. It is due to the fact though that the main README file is not part of the project's documentation per se... I'll try to find a different example for that though ☝️

I disagree, I think it is always very confusing and hard to read if (like mostly) everything is combined into one big file.

Well we can (and should) still put the different topics into different files (server, client, installation, usage, etc). What I really dislike about having a complete set of instructions for every OS is that these will then have quite a big overlap.
This is then just horrible to maintain and very prone to get out of sync if someone encountered that e.g. on Linux the guide is not true anymore and then goes ahead and fixes it in the Linux guide. If this is a detail that is also mentioned in the other guides, we now have 1 correct version and 2 incorrect ones.
If instead the non-platform dependent steps are all in a single file, we avoid duplication and thus fixing or updating can be done in a single place ☝️

I think it is best to have these seperate files and instead I link to the common Client Config Guide and Server Config Guide.

So what's left is basically just installing of the software that'd be written on a per OS basis? In that case I guess that's fine since for the installation there's probably no real overlap between the instructions for the different OS 🤔

[toby63]

So what's left is basically just installing of the software that'd be written on a per OS basis? In that case I guess that's fine since for the installation there's probably no real overlap between the instructions for the different OS 🤔

Almost correct: The Guides include information on download, installation and starting (of both Client and Server) directly and links to the client and server configuration.
So if there are no differences regarding the configurations between the Operating Systems, this should work.

[Krzmbrzl]

Okay then that sounds like a plan 👍

[Krzmbrzl]

We currently don't have plans for that.

[toby63]

I remembered a discussion about the naming and now it is not planned anymore?
#4046

[Krzmbrzl]

It never was planned to rename the executable (afaik). This discussion was more referring to how the server should be referred to (in package archives).
@davidebeatrici did I misunderstand this?

[toby63]

Update: Binary names will probably be changed, see #4046.

[Krzmbrzl]

Given that our shortcut menu currently is not the most intuitive thing to use, this might be a good idea 👍

[toby63]

Will see how good or bad that will work :D.

[toby63]

I did some testing with the gifs and right now it seems I am not able to make that work properly (filesizes to big, picture to small, quality to bad). Quess I do something wrong.

But I will keep trying; as an alternative I might just create a very short gif with the main steps (clicks) manually...

[toby63]

Note regarding progress: This is halted for now, because:

1. I noticed that there are some (or even many) changes coming for 1.4.0 and I have no interest in rewriting everything etc., thus the guide will probably continue when 1.4.0 is in some kind of feature freeze.
2. I don't have time and interest right now to continue.
3. No one responded yet for the requested information or collaboration on some specific guides.

[Krzmbrzl]

Closing this as stale