add support for doc modpack?

[Desour]

I've already started to add some support to @Wuzzy2's doc modpack and I recognized, it's very easy. (There are already doc folders in the mods.) So, should I continue and open a pull request?

[Jeija]

I have to disagree as long as the documentation system is not standardized. I'd rather not add some specific code for one particular other mod. How can I be sure that e.g. minetest_game don't add their own system in the future and Wuzzy's mod will become obsolete?

I will leave this open for discussion, but from my perspective I'd say there are propably better ways to improve mesecons (e.g. code cleanups, improve documentation text on website, ...) than to put much effort into this.

[Desour]

ok

[Wuzzy2]

:-(

I don't know what you mean by “standardized”.

But I do know this: Just because something is in Minetest Game it does not mean it's a “Standard”. It's only a “Standard” within Minetest Game, while other subgames can be wildly different. The Minetest community really should get over its obsession with Minetest Game as if it would be the Lord himself and players must not have other subgames beside him. xD There are subgames which are pretty much different and have completely different APIs or don't even have any API, so any mod which is in Minetest Game can hardly be seen as a “standard”. Minetest Game doing its own Help system (rather than just adopting the help modpack) would be an extreme case of Not Invented Here and I'll probably oppose it. I also don't have any reason to believe this scenario will happen in the near future.

If you have comments about the Help modpack in general, or about the Documentation System, I'd be glad to read your opinions in the forum thread. :-)

The Documentation System is currently the only mod which makes it possible to add any help pages. I have not seen any attempt to replace it so far. I also have not seen a criticism on the general concept of this modpack. But the mod is still pretty young.

Improving documentation texts on website is not a replacement to providing in-game help texts. IMO in-game help is better than help scattered on webpages. I am not opposed to web help at all, I just don't think it should be limited to this. In-game help is way more convenient than forcing the player to “tab out” of Minetest all the time. That's why I put so much effort into the Help modpack in the first place. Or imagine a newbie finding Mesecons the first time on a server. In this case, it is unlikely the newbie will actively search the web for Mesecons help. The chance is even lower if the server is full of difficult-to-understand mods, even if they all have web help. Now the newbie is forced to hunt down the help for each of the mods. Even if the newbie knows about /mods, this gets tedious quickly, especially since many mods don't have any help at all.

The Help modpack was made exactly for mods like the Mesecons mods or the mods from Technic. These mods have non-trivial items which are not self-explanatory, so they need additional help texts. If you now claim Mesecons is unsuited for this, that's a bummer. :-(

Adding support for the Help modpack is often pretty lightweight, especially if it mostly revolves about new items. I tried very hard to make sure that adding item help is as simple as possible and doesn't increase the code size too much. And of course, the dependencies will only be optional. So even if the Help modpack will get superceded later, I suppose the amount of work it takes to rollback the changes would be rather small. But frankly, I don't see any reason to believe this modpack is going to be destroyed in the near future. :P

Also: If mods only support mods which have been “standardized” (whatever that means), the Minetest community will not be going anywhere. Or do you mean you just want to wait to see if the Help modpack will stand the test of time? But well, I still have not yet attempted to convince Minetest Game developers to adopt the Help modpack. I guess I'll try that eventually (if it helps its acceptance among developers), but first I want a couple of more features.

If you're still skeptical about the Help modpack, why not just opening a branch?

And finally, if you need implementation help, I'm here to give advice. :-) If you post the PR, I will pretty sure give my comments.

[Desour]

Uhh, how can you always write that much¿ >_<

The help wouldn't be only useful for newbies, eg. did you know that you can use a single vertical mesecon to get the signal by a pressure plate? Experienced players think, they already know everything and so they don't bother to search for help. => The help could be very useful.

Maybe add a separate mod like the doc_minetest_game mod? But it would make everything a bit more complicated. Perhaps I'll open a branch with the doc edits I've made yet.

[Wuzzy2]

doc_minetest_game is technically a giant hack as it overwrites almost all item definitions of Minetest Game items. I would not really like it to make another mod like this. As I said, support for help texts should normally be added in the mod which adds the feature in question. And yes, you are spot-on, it's the small details where the Help modpack can also be very useful, even for advanced users. For instance, I learned that mese blocks in Minetest Game actually let light through.

Yeah, a link to your repository with your proof-of-concept would be nice.

[Jeija]

@DS-Minetest wrote:

The help wouldn't be only useful for newbies, eg. did you know that you can use a single vertical mesecon to get the signal by a pressure plate?

I absolutely agree to this. Things like these among questions like what "receivers" are, the fact that you can now rotate levers / buttons (even up / down) etc. are all information that is crucial to the player, but not easily avialable. So I'm certainly in favor of improving documentation for mesecons.

@Wuzzy2 I agree with most of what you are saying. Yes, in-game help is more useful to players, especially newbies and minetest_game is not the Holy Grail of minetest mods. I also don't have any issues with the implementation of the help system. I haven't carefully reviewed it, but from a technical point of view, I don't see anything wrong with it. We should be able to optionally depend on the documentation system, so hard dependencies shouldn't be an issue (right?). However, these are the reasons for still not wanting to use the documentation modpack in standard mesecons:

• I don't want to duplicate documentation, which also duplicates work. The documentation on the website should always match the one in the game. Of course this is not technically impossible, but this will require some more work than just writing some help strings.
• As you say yourself "the mod is still pretty young", which is a problem for mesecons. The documentation modpack in its current form is very young, not even two months (with predecessors of the current form dating back for more than one year, but the point still stands) while mesecons is more than five years old and has seen many mods and developers appear and disappear. It just doesn't make sense for us to endorse any attempt at a unified documentation system so early on in its development stage given the reasons below.
• The documentation system is a one person project. This is not to belittle any of your work you put into this amazing mod, but if for some reason you stopped developing the documentation system, it would get out of date with the current state of minetest development very soon (think e.g. new GUI elements in minetest). And "not invented here" is a thing, so if your mod was slightly outdated and some other developer wants to come up with a new idea, they would propably just code a new documentation system from the ground up.
• I don't think the documentation system has the right concept. If you look at different forms of software documentation, what stands out to me, is that the approach of the developers writing the documentation for the users doesn't seem to work in most cases. The most useful help systems are those created by users for users, think about the ArchWiki, the Minecraft / Minetest wikis, help forums or blog entries. This means there has to be an easy and quick way for non-technically versed users to contribute help content, even users who don't even know how to use Git or what exactly GitHub issues are. Apparently some kind of wiki system seems to work really well for most projects. To me, it makes more sense to improve the information on the minetest wiki (there already is really good content for minetest_game in multiple languages) and extend it to other mods. Especially mesecons / technic can benefit from longer articles with user contributions on a wiki-style platform. Now with minetest's HTTP API it should be possible to include dynamically updated online documentation into the game.

That being said, I'd be fine with:

• A doc_minetest_game-style mod. First seperate from mesecons, but if the documentation system sticks around, it will be included in mesecons in the future. If the only way to make this possible is "technically a giant hack", that is okay with me (e.g. we could optionally depend on all mesecons mods and auto-generate the documentation from all the doc subdirectories using a script). On the other hand, I don't quite understand why it would be technically impossible to change the documentation system to have it so that this can be done without a hack (would propably make the code of the documentation system less clean).
• A seperate documentation branch. I am not going to maintain that branch, but I'd be willing to promote it e.g. in mesecons' forum topic.

[Wuzzy2]

I don't think the documentation system has the right concept.

I disagree. Especially since I heard many complaints in the forums over and over again about mods they don't understand. But I have other reasons for my opinion.

The most useful help systems are those created by users for users, think about the ArchWiki, the Minecraft / Minetest wikis, help forums or blog entries.

There are multiple problems with that:

• Wikis are very bad it comes down to crunshing numbers (weapon damage, and other stuff which can be parsed) and categorizing, since nothing in a wiki is automated
• Don't even get me started when you actually want to translate those texts! Data inconsistency level is over 9000!
• Thus, wikis waste a lot of precious contributer time (I think over 50% of the work in a wiki only goes into boring stuff like fixing crafting recipes, numbers, and the like; stuff which should all be parsed)
• Wikis are never synced with the current software version
• Blogs are very informally written and do not replace a proper documentation
• Some features are so obscure, only the developer knows them. My rule of thumb is: Document your own code, it's the easiest way to make sure no feature gets forgotten
• Therefore, most players are not always the best help authors either, especially since they don't know about the small details which can be easily overlooked, or even introduce small factual mistakes. IMO the best people to write documentation are committed players AND (to an extent) developers, or at least are able to read and understand code. This is because they need to understand precisely how the game works, but also how players think. Example: I bet we still would not have a wiki page on the rather obscure Desert Sand Soil if it weren't for me. This is something many players will not see if they never looked at the code
• Documentation should not be rewritten all the time. Just get it right the first time; changes between releases
• Wikis give developers an excuse to not document their own code

There's another reason why I am advocating in-game help: The documentation of the stuff is very close to the code which defines the stuff. It is very easy to crunsh the numbers and parse crucial gameplay information which is usually very tedious to extract manually.

Maybe later (VERY later) I add a function to my modpack to generate HTML pages for the web. It might be easier than it sounds (just a ton of work), I already hacked a simple script together to partially auto-generate the Smelting wiki page (see its discussion page). This would also solve Mesecons' potential problem with duplicate texts. The problem you mentioned is a very valid reason and I fully agree.

so early on in its development stage

I agree the mod is young but it is not at all in an “early development stage” anymore. It just apparently hasn't seen much real world use by actual users.

But yeah, overall I can understand you a bit. But note there are already several mods which adopt this help modpack. But currently “only” mine, but plenty of them! :-) I also really wish more people would actually use this thing to find possible problems. I already tested as good as I can (I took some days only for testing), but of course there's always the possibilities for errors. I just hope not every modder thinks like you, otherwise I'd have a really hard time. :D

Now with minetest's HTTP API it should be possible to include dynamically updated online documentation into the game.

Oh god, no. You're introducing a single point of failure. If the player doesn't have Internet access, then there's no help. If the server breaks down, there's no help. It introduces another totally avoidable delay. Also, it is hilariously redundant: First you ask help writers to extract information of the game code and write it to the web, only so the game can download it and display it in the game again. This idea is so wrong an so many levels. I don't even know where to stop.

A doc_minetest_game-style mod.

No, please don't. It has a similar problem like wikis, in that it is completely separate from the actual mod. Meaning devs now have to maintain 2 mods, the help authors constantly have to “hunt after” the actual mod and users have to struggle with 2 mods as well. It just creates clutter and often inconsistency. One user already complained about the simple fact that doc_minetest_game is a separate mod.

Fun fact, doc_items initially had functions to hack-freely add help texts for existing items. But I have dropped these functions in favor of a much simpler approach: That is, putting as many information as possible into the item definition fields. Because I really think keeping the help texts in a separate mod is usually a bad idea which is just inviting a ton of headaches. Also, doc_minetest_game will (hopefully) become obsolete one day when I convince Minetest Game developers to adopt the Help. I see doc_minetest_game only as a temporary solution.

I'd rather wait until you are convinced adopting the help modpack is good.

So yeah, overall I understand why you are still a bit cautious. I better stop convincing you to adopt this modpack. I come back to you after a few more version updates and I managed to make other modders adopt the Help.

[Desour]

#308 (If someone wants to see how I would have done it.)