[Discussion] Documentation

[Evergreen]

I have been reading about what makes good documentation recently, and I have noticed how lacking it is in the introductory area.

These blog posts have some great ideas that I think should be taken into consideration:

• http://stevelosh.com/blog/2013/09/teach-dont-tell/
• http://jacobian.org/writing/great-documentation/

Note
The documentation in lua_api.txt is great, except it is no help at all to a beginner. We need something more than the tutorial that we currently have. Take django for example, it has some of the best documentation ever written. (imo)

[Krock]

I agree, lua_api.txt is not easy to read but there are already some good articles at the dev wiki.

[Esteban]

+1
I think some pages at dev wiki should add more examples. Most of the trouble I went through was that I did not know where to place given code.

I would like to help, but I don't know much besides basic stuff... :P

[Evergreen]

The wiki is not really kept up to date. I agree that it is very useful, but it would be nice if that documentation was a part of the minetest source code in one way or another.

EDIT:
There are some good articles on the wiki, but they are not organized very well. I think it would be good to create something similar to the Steve Losh's structure.

[Baggypants]

What would be nice for people like me experimenting with mods would be a script that parses all the mods and generates a bunch of html pages with crafting instructions.

[Sokomine]

What would be nice for people like me experimenting with mods would be a script that parses all the mods and generates a bunch of html pages with crafting instructions.

Like a craft guide in html? There is a mod/script out there that creates html pages for individual mods.

The documentation in lua_api.txt is great, except it is no help at all to a beginner. We need something more than the tutorial that we currently have. Take django for example, it has some of the best documentation ever written

For a real beginner, some simple sample code as to how to register a new node and then subsequently adding further features to that node might help most. The current documentation might be a bit overwhelming in that area. And then there's the question of how extensive a tutorial ought to be. Teaching Lua might be beyound its scope. AFAIK there was a basic modding tutorial out there which didn't went very far but showed the basics in an easily comprehensible form.

[philipbenr]

As for html: It would take a bit of css to get the organization really nice and, but you can really easily make a minetest-like-formspec idea in plain html. I will look into the script you described.

[Linuxdirk]

Is there something like PHPDoc for Lua? That would minimize the amount of redundancy since all API calls can be documented in the source code and online documentation can be generated from it.

[rubenwardy]

Doxygen supports Lua, iirc.

An automatic craft guide website wouldn't work for my food mod, as the craft recipes change depending on what other mods are installed.

[Sol]

Doxygen supports Lua, iirc.

A proof link, please?

[twoelk]

I guess the main problem is not so much the form or the content but rather the commitment. Writing a good documentation is hard work and with a project as this it is pretty much endless and allready huge. Here is for example a very incomplete list of some of the mods made for Minetest. Feel free to add information. I presume though with a developing software such as Minetest happily is such a list could never offer all the information a player really needs. Very important for example would be to know for each mod for what Minetest version exactly the mod still works. Happy testing.

The Mod Database is allready a pretty good start but it lacks contributers that add the hundreds of mods that exist and test them and describe them and take pics and ...
Besides that it wants the mod-makers to manually update any changes such as download links for new versions. For it to really work the Mod-Database probably expects to much work from modders that work with rolling releases for example.

I personally think the wiki at http://wiki.minetest.net is the best place to gather information and links for the usuall player, just as the http://dev.minetest.net is for those wanting to start developing. I don't say they are perfect yet but we still have to find the knowledgable writer with ambition, time, commitment and good style to help us out. Once the basic information is complete things like this "Beginners Guide to Modding" should be a lot easier to put together. Maybe the dev-wiki could use a better category system or rather at least make full use of it.

There still seems to be some work ongoing for a single or double A4/letter size cheatpage for the basic things to know when playing Minetest but it hasn't been presented yet. (poke-poke-at-hoodedice)

Interestingly the Minetest download does contain a doc folder with usefull content. It might not be that reader friendly but the irritating thing is people asking for documentation are often fully unaware of its existence. I guess this can only be helped (a little at least) with a nice help page within the running program that offers information on where to locate help. Although if this includes hand copying long path addresses most will probably not bother and rather ask for links in the forums or IRC. People are used to having information just one click away.

As Sokomine mentioned Cornernote once wrote a script that extracts information and puts it into a wiki of sorts:

Game Wiki for Minetest

Description
Extracts all in-game items which can then be viewed on a website.

Server admins may want to make this website public so that players can learn more about the world.

It works as follows:

• install (see the README.txt)
• load your game, which dumps all the items to JSON encoded strings inside wikidata/
• load import.php in a browser to import the JSON data into SQLite3
• optionally recompile minetest to extract cubeimages
• that's all, now you can browse your own Minetest GameWiki!

Though alone not that pretty it may serve well as a base to start a documentation from. Sadly you have to do some work yourself to have this thing work, so no one-click-solution.

By the way I think the same of any other automatic systems I have yet seen. They might generate some basic info but it usually needs some write up to be comprehensible and usefull for the common newbie who would be the average customer searching for help and above all guidance.

eh - too much text - no one is gonna read this - just like the allready existing docs

[Topywo]

eh - too much text - no one is gonna read this - just like the allready existing docs

Read it ;-)

[Calinou]

I would like a lua_api.html – basically lua_api.txt, but in HTML form. Or, perhaps a lua_api.md in Markdown.

Very important for example would be to know for each mod for what Minetest version exactly the mod still works. Happy testing.

In our day and age, mods rarely break (however, most outdated mods aren't nearly as good as recent ones). Only mods made prior to 0.4.0 release are likely to not work.

Doxygen supports Lua, iirc.

I've heard that MOBF uses it, but its use in all mods would probably be frowned upon, judging how it looks “bloated”.

[Evergreen]

I don't think automated documentation is a good idea. Please read Steve Losh's blog post before you post here.

[hoodedice]

poke-poke-at-hoodedice

*cough* finals next week *cough*