Documentation Plan

[toby63]

• Create a seperate documentation repo?

• where should the documentation be stored (in the main repo, the website repo or a seperate repo)?

• what documentation do we/you want (also in relation to the wiki):
  Priority:

  • must have
  • good to have
  • can be ignored/deleted

• what should be converted from the wiki (I assume everything needs a rewrite)

• structure for potential translations?

• If it's done via pull requests, is there a way to collaborate on existing pull requests?

Related:
Pull Request with TYPE label: "Docs"
mumble-voip/mumble#4628

[Krzmbrzl]

Separate documentation repository

The benefits I see are

• Docs are not buried in some corner of the website "code"
• Because of the above: More readable & easier to find/parse

The disadvantages I see are

• Requires yet another repo that needs maintenance (though this is probably only a minor issue)
• Does not fit the current automation of the website being updated by the CI in the www repo

[toby63]

Does not fit the current automation of the website being updated by the CI in the www repo

If you want to implement the dev docs (from the main repo) as well, you will need a slightly different solution anyway.

[Krzmbrzl]

Where to store the documentation

If we create a dedicated documentation repository, then we should definitely use that (what's the point of it otherwise?). If not, then the website's repo is the way to go (imo).

This all applies to end-user documentation. The developer-related documentation (e.g. build instructions) should (also) be contained in the main repository as this is where the source code (and thus the developers) are. It may in addition also be on the website but the main repo has priority for this (imo).

Ideally though we would indeed have both: docs in the main repo and on the website. In order to achieve that we could use some sort of automation (no manual duplication!) to sync one with the other.
I guess the easiest way would be to maintain the dev docs in the main repo as markdown files and then including that whenever the website docs are built (we use hugo so converting markdown to HTML is not an issue). This would of course restrict us to pure markdown for the website version but since we want it that way in the main repo, that's fine.

The other way would be to maintain the dev docs in the docs repo and sync it to the main repo whenever it was changed. If we allow hugo extensions (e.g. shortcodes) in the docs, these would have to be removed and the docs had to be converted to "proper" markdown in order to be easily readable in the main repo. This is probably a bit tricky.

[toby63]

I guess the easiest way would be to maintain the dev docs in the main repo as markdown files and then including that whenever the website docs are built (we use hugo so converting markdown to HTML is not an issue).

👍

Only remaining problem is, what is defined as dev docs and what not, but thats probably a case-to-case discussion for pull requests in the future.

[Krzmbrzl]

Yep, I think so as well.
I think there are obvious cases such as the build instructions for the code. Less obvious and probably debatable is for instance Ice scripting... But yeah, I guess this is best discussed on a per-PR-basis ☝️

[Krzmbrzl]

Import range & priority

In general we can say that everything that is currently on the wiki that is not outdated is something that we want to eventually be contained in the new docs. This answers the what.

The question of the priority of the "import" operations is a bit more tricky and probably rather subjective. Imo a meaningful prioritization would be to follow a new user's steps approaching the software. Thus the order/priority list could look something like this:

1. Installation
2. Starting it up
3. Usage
4. Configuration
5. Administration

[toby63]

What I meant is a concrete list, not the scope etc., because that is clear already.
All of the above points are already targeted by my pull request for user-guides (though that is not ready yet 😄).

[Krzmbrzl]

There will be not concrete list (I am rather sure of that). Whoever wants to start working on it, will decide that 🤷

[toby63]

Already assumed that.

[toby63]

Just a short example for a plan:

Lets look at the startpage of the wiki.
Note: All comments about deletion etc. apply for the future, not necesserily right now.
We see:

• Main:

  • Installation (part of new documentation; part of PR 4628; should be deleted on wiki)
  • FAQ (probably needs update; should be on the website)
  • Features (probably needs update; should be on the website)
  • Contributing (should be on the website, see Contribute: Rewrite and Restructure #123 )
  • Development (seems outdated and should probably be replaced by a development documentation)

• Client

  • Positional audio plugins (documentation; seems fairly recent)
  • Skins (documentation; should be merged with Themes and updated)
  • Usage Statistics (don't seem to exist anymore, also whats the sense of this page in this category?; deletion)

• Server

  • Running Murmur (documentation; now part of PR 4628; deletion on wiki should be discussed)
  • ACL & Groups (documentation; should maybe be a part of the new server guide: PR 4628; deletion on wiki should be discussed)
  • Commercial Hosting (should probably be a part of the website (to some extent it already is on the homepage (https://www.mumble.info/#hoster-features); additional notes might be something for the documentation)
  • DBus and Ice (documentation; dbus should probably be deleted (because it's deprecated); the Ice page needs some work, to have a better overview, structure etc.)

---

And these short notes should be added to all the pages:
What to keep and what to delete; what needs work; what has priority and to what category should it belong.
Overview of all pages on the wiki: https://wiki.mumble.info/wiki/Special:AllPages

This is what contributors need, to know what to work on and in which way.

[Krzmbrzl]

Problem is: I don't have the time to go through each and every page that currently exists on the wiki. Thus I always want to simply put this decision in the hand of potential contributors, since that person will have to go through the respective page anyways and imo for most cases common sense is enough to decide. And in other cases, I'll happily answer questions :)

[Krzmbrzl]

Results from our meeting

So we discussed how we want to proceed with the documentation in our meeting today and this is what we came up with:

• We want to get rid of the wiki
• We want to create a new top-level directory in the mumble-www repo that will hold the user-documentation

For migrating the documentation from the wiki to markdown files we intend to use an automatic export tool. The process would be something like this:

1. Freeze the wiki so no edits can be made to it anymore
2. Export all docs from the wiki to markdown files using an automatic converter
3. Proof-read all auto-generated markdown files
4. While proof-reading take notes on what parts of the documentation needs to be updated/reworked/deleted
5. Upload the markdown files to the www repo
6. Publish documentation on Website
7. Delete wiki
8. Based on our notes, create a ToDo list of things that need to be done in order to update and improve the documentation

We need to prepare this properly though, so the migration won't start immediately. Until then all docs should be edited in the wiki as before.

We also want to write up some guidelines on the general layout pages in the new documentation should follow. These probably won't be all that different from what we currently have in the wiki though.

[toby63]

Ok, that sounds very good 👍.

Maybe you can message me, when the whole thing is about to start (don't worry, I don't expect that to be soon).

create a new top-level directory in the mumble-www repo that will hold the user-documentation

That would be good to know for my PR of the basic user-documentation (mumble-voip/mumble#4628).
Though that will take some time to be finished.

[Krzmbrzl]

Maybe you can message me, when the whole thing is about to start (don't worry, I don't expect that to be soon).

Will do. You can probably expect it to start in roughly 2-3 weeks (if we don't encounter any problems down the line) ☝️

That would be good to know for my PR of the basic user-documentation (mumble-voip/mumble#4628).
Though that will take some time to be finished.

We have to verify that the process will end up functioning the way we thought it does, but if that is the case, this decision is pretty much final. Don't worry about your PR though. The docs are only markdown files and therefore easily transferable.