Implement documentation page
Opened this issue ยท 10 comments
Intro to our different types of configuration
- Collect some requirements - mandatory and optional/wishes
- Add a docs landing page
- Migrate slice docs
- Migrate Ice docs into scripting page with subpages
- Establish a menu navigation
- Migrate server setup guide
- Map out migration order (ACL, features, translation, FAQ, scripting, theming, development)
- Figure out if and how to integrate (or just link) protocol documentation
Mandatory Requirements
- Figure out if and how to take over existing content (content history and copyright/author naming), maybe for each page individually
Wishes
- Edit page link to allow easy submitting of PRs โ
General References of good documentation pages
- docs.microsoft.com
- GitHub integration
- Page and in-page navigation and index
- Edit page via PR
- GitHub issues displayed and linked on pages
- Hugo documentation https://gohugo.io/content-management/menus/
docs.microsoft.com
is definitely what we should take inspiration from.
They use markdown for pages, meaning that the end result (without the theme/style) can be previewed.
I think I will make this a multi part and partial process.
Migrate some content, then establish frontend tech like the page navigation, then menu navigation, and only then more content.
Seeing some of the content, I want to also improve the structure. Adding a hierarchical structure to our shitty wiki structure should yield a great improvement IMO.
Additional references:
- bep/docuapi is a Hugo theme for documentation (demo)
- SCSS
Once mumble-voip/mumble#4628 is ready, it could be included.
@vrifox maybe you can use this issue as some sort of context for potential future discussions/projects/involvement/you name it :)
I created a tool that converts page + revision + author data to git commits and markdown files with frontmatter. One result see #187
@Krzmbrzl and @vrifox went through the wiki pages to determine which pages would even be potentially worthwhile to migrate - current draft/selection at https://github.com/Krzmbrzl/mumble-wiki-export
@restitux was the one who took initiative with the wiki export (tagging to include into the conversation here)
I'll list a table of the pages included in the mumble-wiki-export that are potentially worth to then assess and migrate them:
wiki page | Desc | Assessment | Status |
---|---|---|---|
acl tutorial | resolved by PR #188 | ||
acl and groups | resolved by PR #188 | ||
mumble acl example | how-to force guests into channel | branch docs/acl-guestchannel |
user docs
wiki page | Desc | Assessment | Status |
---|---|---|---|
logitech g-keys | PR #190 | ||
Seems entirely trivial; not worth docs | Skip | ||
installing mumble | Very old; a lot of different OS/pkgs | possibly/partially outdated, would need assessment, can create new content as need arises | Skip |
audio | PR #193 | ||
client settings | PR #194 | ||
faq | a lot of content | ||
features | generic, broad overview, missing newer features | can skip | |
mumbleguide | outdated Advanced |
admin docs
wiki page | Desc | Assessment | Status |
---|---|---|---|
configuring murmur | |||
how to set up an ldap authentication | |||
murmur.ini | |||
murmurguide | |||
SRV record | |||
running murmur |
dev docs
wiki page | Desc | Assessment | Status |
---|---|---|---|
channel viewer protocol | should be dev docs? | PR #197 | |
skinning | |||
themes | |||
usage of html and css in mumble | PR #197 |
uncategorized
wiki page | Desc | Assessment | Status |
---|---|---|---|
3rd party applications | |||
Ice | we have docs | ||
Link | already doc | ||
Mumble URL | PR #199 | ||
not particularly useful or concrete or up-to-date | |||
3rd-party Android app (client) | trivial and irrelevant stuff; not worth docs; we link to it on DL page | Skip |