Lua documentation on Minetest Developer Wiki is wrong

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

Lua documentation on Minetest Developer Wiki is wrong

by Wuzzy » Mon May 13, 2019 13:17

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: 3435
Joined: Sun Oct 28, 2012 00:05
Location: UK
GitHub: paramat
IRC: paramat

Re: Lua documentation on Minetest Developer Wiki is wrong

by paramat » Thu May 16, 2019 21:54

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: 808
Joined: Sat Oct 27, 2018 08:32
GitHub: runsy

Re: Lua documentation on Minetest Developer Wiki is wrong

by runs » Fri May 17, 2019 08:43

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.
 

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

Re: Lua documentation on Minetest Developer Wiki is wrong

by Pyrollo » Fri May 17, 2019 09:52

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
Member
 
Posts: 684
Joined: Thu Mar 24, 2016 03:19
Location: Right behind you.
GitHub: v-rob

Re: Lua documentation on Minetest Developer Wiki is wrong

by v-rob » Fri May 17, 2019 22:55

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.
 

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

Re: Lua documentation on Minetest Developer Wiki is wrong

by paramat » Wed May 22, 2019 17:25

> 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: 1579
Joined: Mon Jul 11, 2016 21:08
GitHub: tacotexmex
In-game: texmex
 

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

Re: Lua documentation on Minetest Developer Wiki is wrong

by v-rob » Wed May 22, 2019 21:26

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.
 

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

Re: Lua documentation on Minetest Developer Wiki is wrong

by Linuxdirk » Thu May 23, 2019 07:11

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: 3610
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

Progress report

by Wuzzy » Thu May 23, 2019 12:27

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: 2177
Joined: Wed Sep 17, 2014 11:21
Location: Germany
In-game: Linuxdirk

Re: Progress report

by Linuxdirk » Thu May 23, 2019 13:02

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: 1579
Joined: Mon Jul 11, 2016 21:08
GitHub: tacotexmex
In-game: texmex
 

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

Re: Lua documentation on Minetest Developer Wiki is wrong

by Linuxdirk » Thu May 23, 2019 16:57

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: 1579
Joined: Mon Jul 11, 2016 21:08
GitHub: tacotexmex
In-game: texmex

Re: Lua documentation on Minetest Developer Wiki is wrong

by texmex » Thu May 23, 2019 17:26

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.
 

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

Re: Lua documentation on Minetest Developer Wiki is wrong

by Linuxdirk » Thu May 23, 2019 18:39

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.
 


Return to Modding Discussion



Who is online

Users browsing this forum: No registered users and 1 guest