Documentation structure is a mess

[TheLeftMoose]

Enhancement Type

Improve an existing feature

Describe the enhancement

The structure of the documentation, both in the docs folder as also what is pushed to readthedocs is a complete mess. I often find my self searching and finding the same information multiple places, as well we no consistent structure is present.

Also the meta documentation on the documentation setup is non-existient. :)

I would be happy to help with a restructure PR, to give something back to the community. If we start a simple discussion in this issue, maybe you are able to give enough guidance to how the setup is today.

[itzg]

That's a rude way to kick off the discussion.

I guess start listing off things you think I did wrong and we'll go from there.

[itzg]

I often find my self searching and finding the same information multiple places

Please expand on this one specifically

[rhullah]

Yeah, not the great way to submit an issue/suggestion.

I have mixed feelings on this because when I first started using the image, I was a little lost. I knew what I wanted to achieve, but didn't know how to configure it to get there. I didn't know where things were, or what they were called. Having search on Read the Docs helped immensely.

But now, after I've used the image for awhile and understand more of what and how it's doing what it does, I'm able to think "oh that's probably under this section". And, I would struggle coming up with a better structure.

[itzg]

Also the meta documentation on the documentation setup is non-existient.

This? https://docker-minecraft-server.readthedocs.io/en/latest/misc/contributing/docs/

[TheLeftMoose]

That's a rude way to kick off the discussion.

I guess start listing off things you think I did wrong and we'll go from there.

:) well, it is not always easy to get attention right. Ej, I hope you took it a little positive. Firstly deeply sorry for anyone I might have offended.

I have been using this image, bungeecord and rcon for many years and I absolute love the quality and the changes done over the years.
As @rhullah is telling as well, when you use the images you get to know it better, but there is still many querks where manual configurations needs to be done here and there. Epecially when having main-hub+some minecraft servers behind a bungeecord or similar setup, there is some complexity you need to overcome. Also, it is a hobby project as well as many other users, therefore I don't tough the config every day. When the servers run, the docker infra chucking it's way until next mc upgrade. Even as I try to document what I did last time and making some bash scripts, I still have challenges remember each and every reasoning of settings.

Rant over, it might come from the fact that I am starting my setup over and wants to startup a velocity/paper with geyser... I have tried to use the examples and deploying a paper server with geyser with docker compose is as easy as scratching my own head... and it works, but when moving onto adding velocity, there is some coodination secrets files, paper settings file and velocity.toml that needs to be set. and here the documentation lacks some kind of consistansy.

My first thoughts some kind of restructure based on the docker guides and references official documentation. (https://docs.docker.com/get-started/). Then separate the references for all versions, variables and etc. as they more of less list possible inputs (maybe these could be an automated output from the publish process later?)

Another example for inspiration is https://wiki.geysermc.org/

[TheLeftMoose]

Also the meta documentation on the documentation setup is non-existient.

This? https://docker-minecraft-server.readthedocs.io/en/latest/misc/contributing/docs/

maybe this is a good example of good documentation that is relevant, but put in the misc folder.

[itzg]

That's a rude way to kick off the discussion.
I guess start listing off things you think I did wrong and we'll go from there.

:) well, it is not always easy to get attention right. Ej, I hope you took it a little positive. Firstly deeply sorry for anyone I might have offended.

It's actually quite easy to get my attention. I promptly read every issue and try to respond to every message on Discord. Being rude is still not acceptable IMHO. No, I didn't really find anything positive in your post.

I have been using this image, bungeecord and rcon for many years and I absolute love the quality and the changes done over the years. As @rhullah is telling as well, when you use the images you get to know it better, but there is still many querks where manual configurations needs to be done here and there. Epecially when having main-hub+some minecraft servers behind a bungeecord or similar setup, there is some complexity you need to overcome. Also, it is a hobby project as well as many other users, therefore I don't tough the config every day. When the servers run, the docker infra chucking it's way until next mc upgrade. Even as I try to document what I did last time and making some bash scripts, I still have challenges remember each and every reasoning of settings.

This project is also a personal project of mine. I have very limited time and energy to put into this project -- in fact, I have had to purposely back off on daily involvement since I have many other unrelated projects that I have had to delay for many years. I am finally getting started on one of those and it has been such a positive boost to my mental health.

You're sending mix signals, but mostly I feel like you're disappointed in much more than the documentation and that seems even more daunting to address. This project has grown over 10 years in mostly ways that I like and some ways that have been necessarily not so good. Again, it's a personal project and I do as much as I can and am glad to have people contributing where they can.

So, perhaps it's best if you put some effort where your criticism is and submit small, incremental PRs with improvements to the documentation.

[TheLeftMoose]

I am a little sad that you take my comments as criticism, maybe you read it like that since I don't want to step on your great work and just rework it without consulting you first. Sincerely, it is all positive thoughts I'm trying to send and indeed not disappointment in the overall quality of the current documentation.

Again, thanks for your effort with this and the other minecraft projects! It is really appreciated!

So maybe as a first folder draft it could be:

Guides/
|
|- Image Overview
|- Get started (intro.md today?)
|--- Getting started guide
|--- Quick hands-on guides
|------ Sending commands
|
|- Deployment and orchestration
|--- Deploy with docker run
|--- Deploy with docker compose
|--- Deploy with Kubernetes
|
|- Types and platforms specific deployment
|--- Server types
|------x
|------y
|------z
|--- Mod platforms
|------x
|------y
|------z
|
|- Contribute
|--- Contribute to image docs

References
|
|- Variables
|- Versions
|- Data directory layout

[itzg]

Please proceed with a small, incremental PR. Pick one thing from your suggestion and nothing more.

This is very important since the docs have about 2,500 daily views so too much change, even for the better, will disrupt user experience and most likely break external search indexing such as Google.

[mfisher87]

well, it is not always easy to get attention right

I am a little sad that you take my comments as criticism, maybe you read it like that since...

I just stumbled across this issue randomly and I read it as clear criticism and dissatisfaction. I think it's clear you meant well, but can you try to look from a different perspective to understand why it might come across that way? Projects like this are done for fun and we're lucky they're also shared purely out of the authors' generosity. When folks enter the space and don't return that generosity in the form of careful effort to keep the project fun for the owners/maintainers, they're risking the continuation of the project. If a volunteer doesn't want to give you attention, they don't have to, right? Better to try to make it enjoyable to give you the attention you want. Also, documentation is very difficult. As someone who has written a good amount of docs, I can tell at minimum mid-high 2 digits of hours have been spent on the docs for this project, if not 3 digits. Apologies for butting in, I'm just sensitive to this issue and I hope I can help someone understand better... 🙇

If only to justify my participation in this thread beyond lecturing, diataxis was incredibly helpful for developing my mental model for authoring technical documentation. I would honestly say I've never learned anything more useful when it comes to docs!