Pain points when using Minetest

[TumeniNodes]

It's not only about a doc system but "obligate" the developers to write it.

I have to disagree with this. Writing documentation can become a time consuming process, which will definitely slow development even more.
In a "paid" environment, this is a fair part of procedure but, in a volunteer environment it can be a death sentence.

Also factor in that some people are not very good at writing docs.
Best there is a small group or even couple of people who can do this. The only problem there... is finding people who enjoy, and are capable of writing up good/solid documentation.

And then there is an expectation from some, that a dev should write the docs (or notes) as they go but, that can become annoying and a constant distraction.

It is a very tedious venture. Wuzzy has been one of the very few who have contributed to such work.

All of that aside, I would like to see more comments within code, just to quickly explain what is doing what, why, and how and leave some basic options left/added in but commented out.
It may add to congestion and seem like a mess but, it would be quite helpful in a lot of situations.

[paramat]

Meh, i deleted my offtopic ramblings, sorry for that.

[Brian Gaucher]

It seems that Minetest needs people to improve the wiki, forcing core devs to do it, could improve things, but it's still forcing them, which is usually a bad idea. Encouraging everyone to help could lead to lots of sub-par pages.

I would like to join Minetest development, but I'm slowly learning C++, and have played around with modding. I wonder if improving the wiki would be a good (longer project) way for me to improve my modding skills, help the community, and participate in Minetest getting to know it better as I learn C++.

My questions is, would it help me the devs and the community if I tried improving the wiki?

E: Sentence clarification.

[Wuzzy]

I also disagree that lua_api.txt is a huge problem. It's pretty much content complete, and that's what counts. It could maybe be made more readable, but for that we have Markdown and rubenwardy. :D Anyway, I rarely had problems with that file.
lua_api.txt is the best we have right now. There's a reason why this is still the ONLY officicial documentation. Frankly, the dev wiki sucks because it's eternally outdated.

[Astrobe]

I 100% agree that it is critically important to have a version-controlled API reference. Wikis are completely unsuited for critical dev documentation, also because it is not kept in sync with the source code at all. Their history log is completely independent.

Good point on the sync problem.

Also, you can't have documentation for multiple versions of Minetest in a wiki, only “latest” at best, unless you deal with a billion of complicated and painful-to-maintain MediaWiki plugins or extreme redundancy.

I think you exaggerate things about plugins. But even if it's true, at worst one can archive manually pages impacted in major ways by API changes, if keeping the old descriptions on a single page make things messy.

Also: It's a wiki. Which means that everyone with an account can destroy the work of others with a mouse click. It's very easy to introduce errors, whether intentional or not.

Yes, and when it is intentional it is called "vandalism". All major Wikis offer tools to deal with this. By the way, the Emacs Wiki doesn't even require an account to edit a page. Granted, it is terrible practice (especially because it hosts scripts for Emacs, and you can do a lot of damage with that), but it shows that the world isn't as hostile as you may think.

Wikis also tend to degrade fast in up-to-datedness. This is a direct result of the fact they're not in sync with the source code.

Not only. Introducing frictions like spitting player and modder contents between two wikis, or telling modders they document their mod in forum posts, then you are doing the opposite of supporting wiki usage. No surprise at all they fall out of date.

Also, I think it is good practice to force devs

To "force" devs is... Let's say it is just a funny idea.

What will we say to Brain Gaucher above? Don't waste your time on the wiki, it's out of date and will continue to bit-rot. Instead, update lua_api.txt and submit a PR. What, you don't know what a PR is? Go learn Git(Hub|Lab). I tell you, chances are that you'll never see a contribution from him.

Again, let's be realistic and use the concept of Path Of Least resistance:

* a unified wiki for scripting and gameplay (as already mentioned)
* for engine contributors, it's certainly easier to add/edit a Doxygen header than editing a separate, big documentation file. So let's tell the devs that they can just use Doxygen or similar. I think they wouldn't be unhappy about that.

Then in the part dedicated to scripting in the Wiki, you can link to the Doxygen files if you only have time for bare minimum documentation. And then the miracle that made Wikipedia what it is can begin to happen.

(yes, I realize the whole thing is a huge amount of work, but what if it is also a huge step forward?)

It could maybe be made more readable, but for that we have Markdown and rubenwardy. :D

What if RubenWardy decides to leave the community and shutdown his/her server? That would be a severe hit (among many other reasons unrelated to the discussion).

Anyway, I rarely had problems with [the lua_api.txt] file.

Good for you. But maybe that's because you have years of scripting behind you so that there's actually more in your head than in this file. Me, I'm often annoyed by the lack of details. What happens when name doesn't exist in get_int(name)? Well, I'll have to try it. You have to test for it anyway. Except it would be better if the info was right there in the first place: it would remind us to handle that particular case, we could code it right away, there would be less risks that you forget about it and that it blows up someone's server 3 months later because someone made a typo in a name.

There's a reason why this is still the ONLY official documentation.

Yet some others do put ALL of their docs in wikis and are still alive and kicking.