Wuzzy wrote: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.