Add more documentation: crafting, gameplay guide

[paramat]

Crafting

It bothers me that the only crafting documentation is on the internet and in the out of date wiki, i feel that MTG should be self-contained and include a .txt document lisiting crafting recipies for all it's mods. It seems perhaps best to have one document instead of one in each mod, to avoid needing to have multiple documents open at once. Such a document would be updated as part of PRs so will never be out of date.

There is already an issue for a crafting guide, so that doesn't need to be requested here. That has support but is probably distant due to core dev time and priorities. ///////////////

Gameplay guide

How are players meant to discover that you need to craft a mapping kit to use the minimap, or craft binoculars to use zoom, etc? This type of useful gameplay information should also be present as a .txt document in the game folder. The README's of some mods contain this type of information, but it is not obvious to a player to read the README of individual mods, whereas 'game_guide.txt' (or whatever) in the game folder is much more likely to be seen and read. ////////////////

It seems to me that all information needed to enjoy a game to the full should be contained as documentation within the game folder itself.

[Ezhh]

It seems perhaps best to have one document instead of one in each mod

I feel mods should be self contained as possible and have their own documentation, because then they are easier to switch out and replace with other things if the player wishes. I also find it a lot more natural to check a mod for documentation, even when a mod is part of a game.

With that said, a general game guide (that is not intended to replace mods having their own info) could be nice to have. But I do feel there's an issue with this approach.

How are players meant to discover that you need to craft a mapping kit to use the minimap, or craft binoculars to use zoom, etc?

I don't think your average player will think "I better check the docs for what I can do." Some might, but younger players especially are unlikely to even think about docs. If you really feel players need help with such things, it should be in-game help.

[rubenwardy]

:-1:

Craft recipes should be found using a craft guide.

Players never read docs, they'll Google things they're stuck on. This makes the wiki more useful than any documentation

[paramat]

I feel mods should be self contained as possible and have their own documentation, because then they are easier to switch out and replace with other things if the player wishes.

Good point, i agree.

[paramat]

However i agree with the basic points of both of you, about docs not being obvious to refer to, but we can educate players to look at these docs. In-repo docs updated in PRs are the only accurate docs we have, no-one has time to maintain docs elsewhere, as the wiki proves. To be clear, i'm not against in-game guides, this isn't a choice between the 2, it's temporary until those happen, which will be many years.

[rubenwardy]

Wiki will be much less out of date for MTG than the engine, such that it'll be very usable. The API reference is needed to keep it up with drastically changing content. Additionally players are used to wikis as it's the form most used. Barely any games use manuals noadays

I don't need to code a craft guide because a good one already exists

[paramat]

Ok, for a slightly different approach, should each mod contain all it's crafting recipies and essential gameplay information in its README or another file? (not as the intended official documentation or as a replacement for it). I wrote 'map' and 'binoculars' to be this way. It seems to me all mods should self-contain all important information in this way.

[paramat]

rubenwardy, sorry, i was in a bad mood when i wrote an earlier comment, edited. Looking at the wiki, it's more up to date for MTG than i realised.

[tenplus1]

Personally I feel that minetest should have a simple crafting guide included instead of recipe documentation as more people will be inclined to use it.

[paramat]

Re-open, i still think this is a good idea in some form, such as https://github.com/minetest/minetest_game/issues/2239#issuecomment-429584439 Not as a replacement for wiki or in-game help though.

[Wuzzy2]

Crafting

The only sensible solution to that is a crafting guide mod. Almost all games do that (seriously: https://wiki.minetest.net/Crafting_guide#List_of_games_with_crafting_guide) and not just because it's a hype but for very good reasons: A crafting guide mod is very convenient, handles all recipes automatically and is always up-to-date. Once it's up and running, it will be a very low maintenance component of the game. It's win-win-win-win. It's something that has been tried and tested over and over again.

Additionally players are used to wikis as it's the form most used. Barely any games use manuals noadays

That's a poor argument IMO. Classic manuals shouldn't be ruled out just for the sake of it. A classic manual in HTML form can still be hosted online.

Our wiki also has a critical weakness in that it is not versioned. The wiki only aims to cover “latest stable”. If a player is e.g. still stuck on 0.4.16 for some reason, they're screwed. Sure, there's probably some MediaWiki plugin that could do that, but I'm sure it will be a gigantic pain to maintain, nobody wants to do that. The other weakness of wikis is that everything must be done by hand, nothing is automated. Updating technical values such as “at which height do I find diamonds” is a boring, time-consuming and extremely error-prone task. Trust me, I speak from years of experience.

But if documentation is in the repo, you already get all the versioning “for free”.

I also don't buy that players want wikis. It's more about online availability, It won't make a difference to players if it's a static HTML manual or a wiki. As long the documentation is of good quality, it doesn't matter.

Note I don't want to make a strong push towards one direction or another atm. But I just want to point out that The One True Solution doesn't exist, and wikis certainly aren't The One True Solution.

---

FYI: Since paramat said “in-game help”: Here's a mature in-game documentation system:

https://forum.minetest.net/viewtopic.php?t=15912

Unofficial extension for MTG (out of date): https://forum.minetest.net/viewtopic.php?t=15224

[Wuzzy2]

More thoughts: The obvious benefit of wikis is that everyone can edit with a few mouseclicks and doesn't need to deal with PRs or code at all. It's cumbersome to get an account atm, but this might actually be a good thing, becase we don't have problem with trolls or spam. Fixing things will become slower when it's moved entirely to in-repo, and it will eat up time of core devs as well (every change wants to be approved). So there's a downside to in-repo help as well.

In-repo documentation in the form of random text files also has a downside because it's not clear how they can be translated. This would only work if the in-repo help texts are visible in-game.

My help system is very powerful, but it might also be overkill if you use all of the modules. But I made the system very modular so that you can throw away things you don't like.

I think the best possible documention is when none is needed because things explain themselves (apart from the core rules). Terraria is a good source of inspiration because every item has a large tooltip that explains everything. Special items usually have a 1-sentence description, the rest are usually just stats like damage, etc.

I was able to play Terraria (many, many years ago, before I became a FOSS zealot, mind you) very far without ever needing to consult the wiki or manual (with some exceptions at the start). I think this is how it should work. Simply because the tooltips explained nearly everything I needed to know. Terraria had many items with non-obvious functionality, but a one-sentence help text was usually more than enough to even explain the more complex items. And it had a guide character that gave you hints.

Just a few more thoughts about this. I'm currently thinking out aloud, don't take it too seriously.

[ghost]

"Barely any games do manuals today," paramat, really? Minetest comes with no tutorial or in-game instructions.

If a game comes with no manual there is a good chance there's in-game information. Though I had to look up some stuff for XC2 because there is an odd exception.

"Barely any games do manuals." That's a reason for justification for not including a crafting guide?

Sometimes I think you say these things to start controversy.

On Wed, Dec 4, 2019, 8:12 AM Wuzzy notifications@github.com wrote:

More thoughts: The obvious benefit of wikis is that everyone can edit with a few mouseclicks and doesn't need to deal with PRs or code at all. It's cumbersome to get an account atm, but this might actually be a good thing, becase we don't have problem with trolls or spam. Fixing things will become slower when it's moved entirely to in-repo, and it will eat up time of core devs as well (every change wants to be approved). So there's a downside to in-repo help as well.

In-repo documentation in the form of random text files also has a downside because it's not clear how they can be translated. This would only work if the in-repo help texts are visible in-game.

My help system is very powerful, but it might also be overkill if you use all of the modules. But I made the system very modular so that you can throw away things you don't like.

I think the best possible documention is when none is needed because things explain themselves (apart from the core rules). Terraria is a good source of inspiration because every item has a large tooltip that explains everything. Special items usually have a 1-sentence description, the rest are usually just stats like damage, etc.

I was able to play Terraria (many, many years ago, before I became a FOSS zealot, mind you) very far without ever needing to consult the wiki or manual (with some exceptions at the start). I think this is how it should work. Simply because the tooltips explained nearly everything I needed to know. Terraria had many items with non-obvious functionality, but a one-sentence help text was usually more than enough to even explain the more complex items. And it had a guide character that gave you hints.

Just a few more thoughts about this. I'm currently thinking out aloud, don't take it too seriously.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/minetest/minetest_game/issues/2239?email_source=notifications&email_token=AFS4UYROU2IM52CMKUFWWATQW6UFFA5CNFSM4F3JXPNKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEF46L4Y#issuecomment-561636851, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFS4UYT2JFK5XIWWRJ2XCE3QW6UFFANCNFSM4F3JXPNA .

[paramat]

@jastevenson303

"Barely any games do manuals today," paramat, really?

Rubenwardy wrote that, not me. I am sure he meant it too. I actually disagree with him on this.

[rubenwardy]

Games should include in-game information and not rely on external manuals

[paramat]

A craftguide will hopefully be added soon, making this issue less important, so closing as is old and also has a disapproval.