Move Dev-info to GitHub

[Krzmbrzl]

Currently all information about Mumble is on the mumble.info website. This also includes information relevant for development (such as build-instructions).

Looking at other OpenSource GitHub projects though, I think it is more common to have development related information available directly on GitHub and this is what I assume a lot of people would expect (including myself when I first visited this repo).
Besides I think it makes a lot of sense to have e.g. the build-information right where the code lives, so I don't have to search it again when fiddling with the code.

Thus I'd suggest to create a wiki for this project (right here on GitHub that is) and migrate all that relevant information there. Furthermore we could also create a CONTRIBUTE.md file in the root dir that contains instructions on how to contribute to the project.

What are your thoughts on this?

[ianling]

Maybe we could leverage readthedocs.io more, since https://mumble-protocol.readthedocs.io/en/latest/ exists (although these pages are also very sparse in places and need more detail added)

Github's wiki is another good option though. My main concern for any option is the ability to pull a local copy of the documentation for use offline, in case I happen to be somewhere without internet, but this is supported by both readthedocs and the wiki.

[Krzmbrzl]

Well build-instructions don't really have something to do with with the Mumble protocol.
And that would also defeat my main purpose of pulling the docs to where the code lives :)

[Kissaki]

I don’t like readthedocs at all. GItHub wiki does not provide good structure and discoverability either. The interfaces lack what I would want from documentation.

See also discussion/requirements documented in mumble-www for migration of docs.

I agree that we should add at least some basic information and pointers to the repository. There is little reason not to. Although it does duplicate maintenance effort, to keep it in sync.

[Krzmbrzl]

The interfaces lack what I would want from documentation.

For instance? I think for only documenting the developer stuff it is sufficient. I don't suggest moving all docs to GitHub. Only the ones important for developing Mumble. That'd include build-instructions, Coding-style guide, etc.

See also discussion/requirements documented in mumble-www for migration of docs.

Can't seem to find the issue. Mind providing a link? :)

[Kissaki]

mumble-voip/mumble-www#35

[Krzmbrzl]

So no further voices in this discussion?

@Kissaki you still haven't told us what exactly it is the GitHub wiki is missing...

[Kissaki]

Can you show me an example of good GitHub wiki documentation?

Any wiki I have seen I found the navigation and discoverability awful.

GitHub wiki seems like a very basic and limited system, with very small-width layout and bad options for structure and discovarability.

[Kissaki]

You seem to raise two separate concerns here. One is documentation within the project repository (which I generally agree with) and the other being further documentation being moved to the GitHub wiki (which I disagree with).

I doubt the wiki branch being cloned with the git repository is a commonly used advantage.

[Krzmbrzl]

I don't say we should move all of our documentation to the GitHub wiki. It is (as you rightfully mentioned) rather restricted in terms of layout and all.

However I think the layout capabilities are good enough for documenting the dev-related stuff (most importantly: build instructions).

I doubt the wiki branch being cloned with the git repository is a commonly used advantage.

No, but having the docs at the same place when browsing GitHub is.

However I'm not opposed to having the docs moved to the repo in another way (e.g. in the docs folder).

[quite]

I'm really not a fan of github wiki, but I can't really elaborate well on that. I guess it's much of a feeling. But yes, discoverability is an issue. Also, wikis are unfortunately where information goes to die. I have come across several github wikis in that situation. The fact that the wiki source files are in a branch didn't seem to help.

I think docs must be precisely where those who are expected to edit them already are. If the latter are devs, then docs go in the repo. Ideally they are easy to render and view offline on the workstation, and as well of course automatically deployed to web site when pushed to.

No, but having the docs at the same place when browsing GitHub is.

Again, I'm more concerned with being able to edit the docs next to where I write the code. I'm rarely browsing any repo on the web. I find repos, at most. If there is a link to the deployed docs in the README (a file which is often rendered automatically in a prominent place), then that seems convenient for me. Picking a documentation system is another issue :-)

If we're talking about other types of docs, and other editors, then there are probably other considerations. Such as ease of editing...

[Krzmbrzl]

My suggestion would be that we could use the docs folder and in there we should simply use Markdown files for the documentation. I guess that fulfills all requirements, doesn't it?

[quite]

I like that. Low-effort start, and iterate on that. No lock-ins, and possibilities to publish anywhere and automatically.

[Avatat]

+1 for documentation in Markdown files.

[Krzmbrzl]

Plus we could then use something like https://github.com/dauxio/daux.io to generate a HTML-version of that documentation for everyone that wants something more fancy than simple markdown documents ☝️

@Kissaki @davidebeatrici thoughts?

[Kissaki]

Hugo does support that use case. Our website already uses Hugo.

[Krzmbrzl]

Yeah well as long as we can have the files in GitHub as Markdown, it doesn't really matter which software we use to generate the additional HTML version of the docs. It's just essential for the doc to be available directly in-source (or at least near-source) for all Devs :)

[Krzmbrzl]

In our Team-Meeting we decided that dev-related info will indeed be added to the docs directory here on GitHub.