Lua documentation on Minetest Developer Wiki is wrong

User avatar
Wuzzy
Member
Posts: 4089
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

Re: Lua documentation on Minetest Developer Wiki is wrong

by Wuzzy » Post

Yes, you have wasted your time. I am sorry for your loss, but I cannot undo it. Because formspec documentation should be the task of lua_api.txt, and lua_api.txt only. The red warning on the top of the page is there for a reason.

The reason why we do not want the wiki to repeat lua_api.txt is redundancy. Redundancy leads to inconsistency. Inconstency is bad. Therefore, redundancy is bad. Thereore, copying lua_api.txt into the Dev Wiki is bad.

The official way to improve formspec documentation is to edit lua_api.txt instead.

Not all changes in the Dev Wiki are futile. Just don't repeat information. The semi-official purpose of the Dev Wiki is to gather semi-official and official development practices, advice, tips and tricks that cannot be part of a reference documentation.

I have now made an edit that marked all pages that are considered to contain unofficial Lua API documentation for deletion, to absolutely eliminate the last doubt that these pages have to die.
My creations. I gladly accept bitcoins: 17fsUywHxeMHKG41UFfu34F1rAxZcrVoqH

User avatar
Hugues Ross
Member
Posts: 60
Joined: Mon May 06, 2019 22:52
GitHub: Df458
Contact:

Re: Lua documentation on Minetest Developer Wiki is wrong

by Hugues Ross » Post

The official way to improve formspec documentation is to edit lua_api.txt instead.
Yeah, that's the problem. As long as that documentation is stuck in a single text file, it will never be good. Even if we work our asses off to re-arrange and group things properly, actually digging into and understanding this part of API is likely to be very difficult for users. It's a complex system, one that's extremely visual, and I don't think any 100% text-based medium is going to cut it. Moreover, due to its size searching through lua_api.txt is already a bit of a PITA and cramming even more detailed information into it will only worsen this issue.

I'm not saying that this is a reason to keep the wiki, but to point our that the current API documentation is in a terrible state. We can re-organize and rewrite it as much as we want, but I believe this is largely a fundamental problem with the chosen format. I'm not so much bothered by losing a few hours, but I am bothered that our standards for documentation are so low, and that attempts to improve the situation (not just here, but in other situations such as the attempt to at least format the lua api as markdown) are killed.

Post Reply

Who is online

Users browsing this forum: No registered users and 2 guests