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

Lua documentation on Minetest Developer Wiki is wrong

by Wuzzy » Post

The way how the Minetest Developer Wiki treats the Lua API is a horrible broken outdated mess that is actually harmful. The Dev Wiki needs serious fixing.

List of problems with the Dev Wiki:
  • Most Lua stuff is painfully redundant to the official documentation (lua_api.txt)
  • It is not approved by the core devs. ZERO of the changes in the wiki go through the strict quality control process that changes to lua_api.txt have to go through. EVERY edit becomes visible instantly. Everyone with an account can introduce falsehoods with a mouseclick
  • It gets outdated very fast. A huge amount of pages is hopelessly outdated, riddled with holes. There are also internal inconsistencies
  • The wiki is not versioned. It's all just a huge gigantic mess of pages that have no indication on for what version they were written for
  • Despite all of this, there is absolutely zero indication or warning about all of this massive problems.
  • It gives new and upcoming Minetest / mod developers a false sense of “officiality” but it's not. It wastes hours over hours of precious dev time by giving them a fake and broken documentation
So. To clarify: I'm not saying the Dev Wiki needs to be killed off entirely. The Dev Wiki is still fine for documenting common “best pracices” or other community-generated tips&tricks that do not belong to an API documentation. What is good for the wiki is also stuff like a list of useful mods, unofficial group names that people came up with, etc. This can absolutely stay. But what has to go is all of the official-looking garbage because it's counterproductive.

What I request the owners of the Dev Wiki to do:
  • Delete ALL pages that just replicate stuff directly from lua_api.txt. All pages in the “Methods” category have to go
  • Make it clear that lua_api.txt is official, and the wiki isn't. On the main page.
  • Mark every Lua-related page with a warning that it's unofficial
  • On the Main Page, clarify the scope (and non-scope) of the wiki
  • Fix the Main Page to reflect all of the changes.
I cannot do any of these changes by myself because I am not allowed to.
My creations. I gladly accept bitcoins: 17fsUywHxeMHKG41UFfu34F1rAxZcrVoqH

User avatar
paramat
Developer
Posts: 3699
Joined: Sun Oct 28, 2012 00:05
GitHub: paramat
IRC: paramat
Location: UK

Re: Lua documentation on Minetest Developer Wiki is wrong

by paramat » Post

I agree that we need to make it clearer that the wiki is very often out of date, that lua_api.txt should always be checked and trusted, and link to the new auto-updated hosted version of lua_api.txt.

User avatar
runs
Member
Posts: 1908
Joined: Sat Oct 27, 2018 08:32
GitHub: runsy

Re: Lua documentation on Minetest Developer Wiki is wrong

by runs » Post

The problem is that the developers of mods do not update the WIKI. It is obsolete. But it has a few things that api.txt has not.

I propose:
Rubenwardy should create a ContentDB same style platform to create a space for developers, well structured and eye-candy.
Day 42 of the quarantine

User avatar
Pyrollo
Developer
Posts: 385
Joined: Mon Jan 08, 2018 15:14
GitHub: pyrollo
In-game: Naj
Location: Paris

Re: Lua documentation on Minetest Developer Wiki is wrong

by Pyrollo » Post

Wiki should be a place for only sharing dev tips and tricks, and howtos. API reference is not maintainable in the wiki.
[ Display Modpack ] - [ Digiterms ] - [ Crater MG ] - [ LATE ]

User avatar
v-rob
Developer
Posts: 793
Joined: Thu Mar 24, 2016 03:19
GitHub: v-rob
IRC: v-rob
Location: Right behind you.

Re: Lua documentation on Minetest Developer Wiki is wrong

by v-rob » Post

I agree in that the Wiki shouldn't be used for documentation. It should be used for clarification, examples, useful tricks, use cases, and things of that nature. As such, the dev wiki should be purged of much of it's contents and refactored in other parts.

On the other hand, I think that there should also be an automatic lua_api.txt to HTML converter that converts the file to multiple HTML files in logical sections (not just making one huge page) and those should be added as special pages to the dev wiki which can't be changed by normal users and is updated with every release of Minetest. (Perhaps there could also be pages for the current development branch of Minetest for people developing for the next version.
runs wrote:eye-candy.
Why do some people consider this considered a necessity? Simplicity, sanity, and clarity is more important for developers, whereas prettiness is more important for end users.
GUI Core Developer | My Best Mods: Bridger - Slats - Stained Glass | To contact me, send a PM

User avatar
paramat
Developer
Posts: 3699
Joined: Sun Oct 28, 2012 00:05
GitHub: paramat
IRC: paramat
Location: UK

Re: Lua documentation on Minetest Developer Wiki is wrong

by paramat » Post

> I think that there should also be an automatic lua_api.txt to HTML converter [...]

Already done http://minetest.gitlab.io/minetest/

User avatar
texmex
Member
Posts: 1752
Joined: Mon Jul 11, 2016 21:08
GitHub: tacotexmex
In-game: tacotexmex

Re: Lua documentation on Minetest Developer Wiki is wrong

by texmex » Post

Yup, remove the Lua parts already! Especially since we now have nice Lua API docs.
Mods | Support Mesehub: bc1qluuests9rxmlnvpjrhsnyjg9ucwy6z3r0y3srw

User avatar
v-rob
Developer
Posts: 793
Joined: Thu Mar 24, 2016 03:19
GitHub: v-rob
IRC: v-rob
Location: Right behind you.

Re: Lua documentation on Minetest Developer Wiki is wrong

by v-rob » Post

paramat wrote:> I think that there should also be an automatic lua_api.txt to HTML converter [...]

Already done http://minetest.gitlab.io/minetest/
Oooh, I am so totally using this now. So much easier to read and more organized.
GUI Core Developer | My Best Mods: Bridger - Slats - Stained Glass | To contact me, send a PM

User avatar
Linuxdirk
Member
Posts: 2675
Joined: Wed Sep 17, 2014 11:21
In-game: Linuxdirk
Location: Germany
Contact:

Re: Lua documentation on Minetest Developer Wiki is wrong

by Linuxdirk » Post

Wuzzy wrote:But what has to go is all of the official-looking garbage because it's counterproductive.
Everything that is already written in lua_api.txt should not be in the wiki.

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

Progress report

by Wuzzy » Post

Progress report: I while ago, I have added warning templates on some pages saying these pages do not reflect the official documentation.
But I was not crazy and the warning does not appear on every single page. I do not know how to mass-edit pages. Or is it possible to auto-include a template on all pages for a given category?

I have also restructured the modding intro page to be less written as a tutorial and more like a broad overview.

I did not do anything else yet because I am not allowed to do most futher change described in the first post. We have to wait for the wiki admins to step forward.
My creations. I gladly accept bitcoins: 17fsUywHxeMHKG41UFfu34F1rAxZcrVoqH

User avatar
Linuxdirk
Member
Posts: 2675
Joined: Wed Sep 17, 2014 11:21
In-game: Linuxdirk
Location: Germany
Contact:

Re: Progress report

by Linuxdirk » Post

Wuzzy wrote:But I was not crazy and the warning does not appear on every single page. I do not know how to mass-edit pages.
You need a bot for this.
Wuzzy wrote:Or is it possible to auto-include a template on all pages for a given category?
Afaik no. One solution would be prepending some text for all articles in a specific namespace or in a specific category. Not sure if this is possible by configuration alone but it surely is possible via the theme.

Edit: There is a hook for preprocessing raw wiki code before it his handed over to the internal processing system. This could be used to prepend wiki code for the articles. Needs reset of namespace's cache, though.

https://www.mediawiki.org/wiki/Manual:H ... eforeStrip

User avatar
texmex
Member
Posts: 1752
Joined: Mon Jul 11, 2016 21:08
GitHub: tacotexmex
In-game: tacotexmex

Re: Lua documentation on Minetest Developer Wiki is wrong

by texmex » Post

Why not use a wiki with git as backend?
Mods | Support Mesehub: bc1qluuests9rxmlnvpjrhsnyjg9ucwy6z3r0y3srw

User avatar
Linuxdirk
Member
Posts: 2675
Joined: Wed Sep 17, 2014 11:21
In-game: Linuxdirk
Location: Germany
Contact:

Re: Lua documentation on Minetest Developer Wiki is wrong

by Linuxdirk » Post

texmex wrote:Why not use a wiki with git as backend?
MediaWiki is the epitome of versioning and allows an approval-based system for publishing/changes, too (both based even on single pages). The thing is: Most of the features are not used by most projects that use MediaWiki.

User avatar
texmex
Member
Posts: 1752
Joined: Mon Jul 11, 2016 21:08
GitHub: tacotexmex
In-game: tacotexmex

Re: Lua documentation on Minetest Developer Wiki is wrong

by texmex » Post

Yes, but a good thing with many git-backed wikis is that it’s flat-file, hence mass editing would’ve been easier by tools of the user’s choice. I too notice the little use of the MediaWiki feature set. For instance, rich media is rarely seen, therefore not even living up to the ”Media” in MediaWiki. ^_^
But for sure there are other upsides with this software.
Mods | Support Mesehub: bc1qluuests9rxmlnvpjrhsnyjg9ucwy6z3r0y3srw

User avatar
Linuxdirk
Member
Posts: 2675
Joined: Wed Sep 17, 2014 11:21
In-game: Linuxdirk
Location: Germany
Contact:

Re: Lua documentation on Minetest Developer Wiki is wrong

by Linuxdirk » Post

texmex wrote:a good thing with many git-backed wikis is that it’s flat-file
Because having a highspeed caching relational database is worse than messing around with a shit-ton of files and storage reads/writes? No, sorry, the backend has nothing to do with versioning or maintainability or editability. Having a professional wiki project using a proper database is always favorable over flat-file hobbyist nonsense. Sorry, I have a strong opinion on this :)
texmex wrote:hence mass editing would’ve been easier by tools of the user’s choice.
It’s not about the user’s choice of tools – it’s about getting things done. Therefore a bot (MediaWiki has an API for bots) is the preferred way of mass-editing contents. For example: A bot could add a category. But mass-editing – in this particular case – is not needed.

Either hook into the parsing process (good) or change the theme (not so good) to show a message at all content in the article namespace.
texmex wrote:I too notice the little use of the MediaWiki feature set.
And most of the fun is missing! Not to mention the 6 years old outdated version.

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

Either hook into the parsing process (good) or change the theme (not so good) to show a message at all content in the article namespace.
Those are not possible because the admin is, like, never available. The admin is like a ghost. I think hooking into the parsing process is pointless anyway. All those pages that were just ripped from lua_api.txt years ago, they should not exist AT ALL.

So the only option that remains is using a bot as an unprivileged user …

The ideal solution would be to just mass-delete all pages in the categories “Methods”, “Objects”, “Types”. There are other ripped pages as well but only a few, so they can be dealt with manually. But I think unprivileged users are not allowed to delete things …
So the next best solution would be to mass-empty or at least mass-flag these pages.
To be honest, I am a bit frightened to use a bot as well. First, you have to learn a lot before you can do anything productive with a bot. But even when its ready to go, it's pretty risky to let a bot loose on a mass-deletion spree. If I screwed up in the bot code, it might delete the wrong pages. Backup is not an option because, I think, it's not accessible to unprivileged users. >_>

And even if you did all that, the mainpage *desperately* needs updating then, because most links on the mainpage won't make sense anymore. But again, the mainpage is not editable by unprivileged users. I don't know who (besides the admin) is even allowed to touch this page. :-(


So many problems are cause because the admin is never there. Maybe the current admin should give control to the wiki to some other trusted members of the core dev team.


EDIT:
OK, so I recently found an extension for mass-deletion, and it is exactly what we need:
https://www.mediawiki.org/wiki/Extension:DeleteBatch

But again, without a reaction from the admin, this wiki isn't going anywhere. ;-)
My creations. I gladly accept bitcoins: 17fsUywHxeMHKG41UFfu34F1rAxZcrVoqH

User avatar
paramat
Developer
Posts: 3699
Joined: Sun Oct 28, 2012 00:05
GitHub: paramat
IRC: paramat
Location: UK

Re: Progress report

by paramat » Post

Wuzzy wrote:
Thu May 23, 2019 12:27
I did not do anything else yet because I am not allowed to do most futher change described in the first post. We have to wait for the wiki admins to step forward.
Ahh man ... this is a ridiculous mess, we cannot even have the power needed to sort the wiki out.
This proves that having large amounts of MT content on the wiki is a mistake, we need complete control over content and presentation.

I agree that probably 95%-100% of the MT wiki needs deleting, transferring as much as possible into documents in the MT repo itself (which can always be presented nicely externally, like lua_api.txt now is). This makes the information much easier and quicker to update, as part of development, and more likely by qualified people, just like lua_api.txt is.
Anything of importance should not be on the wiki.

I have often suggested that MT documentation should be moved into the MT repos, but some core devs seem to prefer external websites, which is clearly a mistake as the wiki proves.
It is good for MT to be as self-contained as possible, this should be obvious.

Bastrabun
Member
Posts: 125
Joined: Mon Nov 04, 2019 19:48

Re: Lua documentation on Minetest Developer Wiki is wrong

by Bastrabun » Post

Compared to all of you, I'm fairly new to Minetest, so I lack the knowledge of how stuff works in this universe. How it worked for me: I was motivated 10 month ago to change some pages I found outdated. Couldn't edit. Found there's an account to be requested in the forums. Did so. Forgot what I wanted to contribute. Got my account activated half a year later, after dropping a hint in the Unofficial Discord. That's my wiki experience.

Is there a vision at least *someone* (best case: the admin, worst case: anyone willing and able) already has for the wiki?

If I had to guess I'd say Calinou is that admin? Are they still available? If not, what's the Minetest way of making decisions and proceeding?

When I started to find my way around, I often turned to the dev wiki for examples, until I learned of Rubenwardy's modding book, the lua_api.txt and the converted lua_api. Now, whenever something is unclear to me I run a search for an example over all the mods I downloaded from cdb in the hopes someone else already had a similar problem (and solved it). Not the way it should work :-/

User avatar
Linuxdirk
Member
Posts: 2675
Joined: Wed Sep 17, 2014 11:21
In-game: Linuxdirk
Location: Germany
Contact:

Re: Progress report

by Linuxdirk » Post

paramat wrote:
Fri Jun 26, 2020 00:19
I agree that probably 95%-100% of the MT wiki needs deleting, transferring as much as possible into documents in the MT repo itself […] but some core devs seem to prefer external websites, which is clearly a mistake […]
Yeah, it’s sad that the inconsistent and mostly outdated wiki is seen as “the official source for [engine documentation]” (Source) instead of having this directly in the code generating documentation using Doxygen. There even is doxy.minetest.net but unfortunately most of the engine seems not to be properly documented in the engine code.

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

Since today I am finally allowed to edit the main page, and I made some pages to the main page to remove annoying links to annoying duplicated Lua API BS.
I went over a lot of the wiki pages to get rid of the links to the bad pages as good as I can. I didn't hit everything, but the most important page is now free of bad links (I hope). The bad pages still exist, however, but at least there are less links to them. I also made it even clearer that the wiki is not official Lua API documentation by adding links to the REAL documentation and a warning on the introduction pages.

The work is not completely done yet. There's always the chance I overlooked a link somewhere.

I've added a work document here:
https://dev.minetest.net/MinetestWiki:L ... on_Cleanup

I think the main page is now (almost) free of any bad links. The one thing I was unable to get rid of are the sidebar links.
In the sidebar, there are static links to the categories “Methods”, “Objects”, etc. I don't know how to remove them.

EDIT: OK, so apparently the sidebar can be edited here: https://dev.minetest.net/MediaWiki:Sidebar
But I learned you need sysop privileges to edit the sidebar. I don't request sysop privileges, it's only 1 edit (remove all links under “API”)
My creations. I gladly accept bitcoins: 17fsUywHxeMHKG41UFfu34F1rAxZcrVoqH

User avatar
Zughy
Member
Posts: 243
Joined: Thu Mar 26, 2020 18:23
GitHub: belongs_to_microsoft
In-game: Zughy
Location: Italy
Contact:

Re: Lua documentation on Minetest Developer Wiki is wrong

by Zughy » Post

Wuzzy wrote:
Fri Jun 26, 2020 21:42
Since today I am finally allowed to edit the main page, and I made some pages to the main page to remove annoying links to annoying duplicated Lua API BS.
I went over a lot of the wiki pages to get rid of the links to the bad pages as good as I can. I didn't hit everything, but the most important page is now free of bad links (I hope). The bad pages still exist, however, but at least there are less links to them. I also made it even clearer that the wiki is not official Lua API documentation by adding links to the REAL documentation and a warning on the introduction pages.

The work is not completely done yet. There's always the chance I overlooked a link somewhere.

I've added a work document here:
https://dev.minetest.net/MinetestWiki:L ... on_Cleanup

I think the main page is now (almost) free of any bad links.
Commenting just to say chapeau to you, Wuzzy :)

User avatar
paramat
Developer
Posts: 3699
Joined: Sun Oct 28, 2012 00:05
GitHub: paramat
IRC: paramat
Location: UK

Re: Lua documentation on Minetest Developer Wiki is wrong

by paramat » Post

Wuzzy, are you able to delete the duplicated Lua API pages?
If so, please can the core devs give Wuzzy consensus permission to delete any page that duplicates lua_api.txt or any other document already in the repo? You have my support.
If not, who does have the power to delete wiki pages? Surely some MT core devs do?

User avatar
sirrobzeroone
Member
Posts: 222
Joined: Mon Jul 16, 2018 07:56

Re: Lua documentation on Minetest Developer Wiki is wrong

by sirrobzeroone » Post

Just adding +1 good work Wuzzy.

I got caught out early on referencing some of the dev wiki info that was out dated when compared to the api doc...most frustrating.

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

No, I can't delete, and even if I could, we're talking about 100s of pages that need deletion.
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

Hm, this is a really unfortunate discovery. I'd just begun the process reworking the formspec docs in hopes of being able to provide comprehensive and well-organized documentation of Minetest's main UI systems... but I guess it's all going to be deleted?

Guess there's no point trying to improve things around here :/

Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest