[Discussion] Documentation

User avatar
Evergreen
Member
 
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
Location: A forest in the midwest
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen

[Discussion] Documentation

by Evergreen » Mon Nov 17, 2014 18:23

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:

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)
Back from the dead!
 

User avatar
Krock
Developer
 
Posts: 4409
Joined: Thu Oct 03, 2013 07:48
Location: Switzerland
GitHub: SmallJoker

Re: [Discussion]Documentation

by Krock » Mon Nov 17, 2014 18:28

I agree, lua_api.txt is not easy to read but there are already some good articles at the dev wiki.
Look, I programmed a bug for you. >> Mod Search Engine << - Mods by Krock - DuckDuckGo mod search bang: !mtmod <keyword here>
 

User avatar
Esteban
Member
 
Posts: 873
Joined: Sun Sep 08, 2013 13:26
Location: Somewhere in the Caribbean...
GitHub: Esteban-
IRC: Esteban
In-game: Esteban

Re: [Discussion]Documentation

by Esteban » Mon Nov 17, 2014 18:30

+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
 

User avatar
Evergreen
Member
 
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
Location: A forest in the midwest
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen

Re: [Discussion]Documentation

by Evergreen » Mon Nov 17, 2014 18:55

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.
Back from the dead!
 

Baggypants
Member
 
Posts: 30
Joined: Mon Aug 25, 2014 17:42
GitHub: Baggypants

Re: [Discussion]Documentation

by Baggypants » Mon Nov 17, 2014 22:21

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
Member
 
Posts: 3913
Joined: Sun Sep 09, 2012 17:31
GitHub: Sokomine

Re: [Discussion]Documentation

by Sokomine » Mon Nov 17, 2014 22:36

Baggypants wrote: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.

Evergreen wrote: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.
A list of my mods can be found here.
 

User avatar
philipbenr
Member
 
Posts: 1688
Joined: Fri Jun 14, 2013 01:56
Location: United States
GitHub: philipbenr
IRC: philipbenr
In-game: robinspi

Re: [Discussion]Documentation

by philipbenr » Tue Nov 18, 2014 00:58

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.
 

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

Re: [Discussion]Documentation

by Linuxdirk » Tue Nov 18, 2014 02:28

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.
 

User avatar
rubenwardy
Moderator
 
Posts: 5886
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: [Discussion]Documentation

by rubenwardy » Tue Nov 18, 2014 07:47

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
Member
 
Posts: 73
Joined: Thu Jul 31, 2014 05:21
In-game: sol

Re: [Discussion]Documentation

by Sol » Tue Nov 18, 2014 09:11

rubenwardy wrote:Doxygen supports Lua, iirc.

A proof link, please?
There is no such thing as duty. If you know that a thing is right, you want to do it. If you don't want to do it—it isn't right. If it's right and you don't want to do it—you don't know what right is and you're not a man. -- Ayn Rand
 

twoelk
Member
 
Posts: 1332
Joined: Fri Apr 19, 2013 16:19
Location: northern Germany
GitHub: twoelk
IRC: twoelk
In-game: twoelk

Re: [Discussion]Documentation

by twoelk » Tue Nov 18, 2014 09:42

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:
cornernote wrote: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
 

User avatar
Topywo
Member
 
Posts: 1721
Joined: Fri May 18, 2012 20:27

Re: [Discussion]Documentation

by Topywo » Tue Nov 18, 2014 10:35

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


Read it ;-)
 

User avatar
Calinou
Moderator
 
Posts: 3157
Joined: Mon Aug 01, 2011 14:26
Location: Troyes, France
GitHub: Calinou
IRC: Calinou
In-game: Calinou

Re: [Discussion]Documentation

by Calinou » Sat Dec 06, 2014 09:07

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

twoelk wrote: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.

rubenwardy wrote: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”.
 

User avatar
Evergreen
Member
 
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
Location: A forest in the midwest
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen

Re: [Discussion] Documentation

by Evergreen » Sat Dec 06, 2014 13:22

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

User avatar
hoodedice
Member
 
Posts: 1372
Joined: Sat Jul 06, 2013 06:33
Location: world
GitHub: hoodedice
IRC: hoodedice
In-game: hoodedice

Re: [Discussion] Documentation

by hoodedice » Sat Dec 06, 2014 13:47

poke-poke-at-hoodedice


*cough* finals next week *cough*
7:42 PM - Bauglio: I think if you go to staples you could steal firmware from a fax machine that would run better than win10 does on any platform
7:42 PM - Bauglio: so fudge the stable build
7:43 PM - Bauglio: get the staple build
 


Return to General Discussion



Who is online

Users browsing this forum: No registered users and 2 guests