Lua documentation on Minetest Developer Wiki is wrong

[Wuzzy]

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.

[Hugues Ross]

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.

[Hugues Ross]

*Bump*

I recently returned to the community after a ~6-month hiatus, but apparently the pages are still up. Is there a timeline for this process, or has the situation changed at all?

[philipbenr]

There have been a couple of people that have done work on making it better here on the forums / making tools to help with that process, but I haven't seen much changes.

One tool I'd suggest if you want to split everything out of a single text file would be Obsidian Markdown Editor, as it supports adding images, as well as linking between files. Granted, this is a very specific tool that other people won't always want to download, but if you want to create a robust knowledge base, this is definitely a tool to look at. I've been using it with git to bypass cloud services that aren't as private.

[Wuzzy]

Well, the challenge is that there is no easy way in MediaWiki to mass-delete pages, or at a way to mass-categorize pages. If that would be possible, it would already have been done.

[rubenwardy]

Update: Zughy and I have deleted over 450 pages from the wiki. These were mostly outdated reference style pages; we kept pages that had useful examples to be salvaged, as well as any pages containing helpful tips.

You can see a list of deleted pages here: https://dev.minetest.net/Special:Log/delete

[Wuzzy]

Thanks a lot! This was long overdue.

Note the main page now needs updating. The following should be removed:

WARNING: This wiki is NOT the official Lua API documentation! It's wrong on many Lua API topics. See [[Lua API Documentation]] to find the real documentation.

Because the warning no longer applies. The biggest problem was the huge amount of pages ripped from lua_api.txt, but since they are now gone, the warning is no longer needed.

As for the remaining pages:

- minetest.spawn_tree can be deleted safely, its example is on another page already.
- Category:MissingExample can be deleted safely, it's an empty category now and it was only used for method pages (which are now mostly deleted)
- settingtypes.txt: can be safely deleted. Completely ripped from lua_api.txt
- PerlinNoise: can be safely deleted. Completely ripped from lua_api.txt
- Mapgen_objects: Doesn't seem to contain any more information than lua_api.txt
- mg_flags: Probably useless
- Games: Almost entirely ripped from lua_api.txt. The remaining text is too little to be useful

A probably problematic deletion:
- GitHub: Linked from main page

Finally, the page "MediaWiki:Sidebar" (special page for the sidebar) should remove the "API" section as this is all part of the redundant Lua stuff.


An unrelated problem on the DevWiki: The <source> tag is broken. Many pages use this tag but it fails to render.

[snoopy]

Thanks a lot! This was long overdue.

Note the main page now needs updating. The following should be removed:

[...]

How is the status on the MT Dev Wiki today?

@Wuzzy might not be involved in maintaining the MT Dev Wiki but the a.m. outdated wiki statement was removed thanks to his request, apparently.

However, as of today the garbled links might show some issues and need for further updates, I presume.

My five cents.