Modding Tutorial Book (new: Code architecture, unit testing)

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

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Post

Hi all, I have created the formspec chapter. I am not completely happy with the phrasing. Is there anything you think it is missing?
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Minetest Tutorial Book - Creating Better Documentation

by Don » Post

rubenwardy wrote:Hi all, I have created the formspec chapter. I am not completely happy with the phrasing. Is there anything you think it is missing?
You made me a happy man. I might actually learn something!!!!! Thanks
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

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

Re: Modding Tutorial Book - Creating Better Documentation

by philipbenr » Post

The problem I saw with markdown, is there are so may different ways. HTML/CSS is pretty normal. Also, I didn't know you could add HTML/CSS to markdown.

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

Re: Modding Tutorial Book - Creating Better Documentation

by Evergreen » Post

philipbenr wrote:The problem I saw with markdown, is there are so may different ways. HTML/CSS is pretty normal. Also, I didn't know you could add HTML/CSS to markdown.
philipbenr, you obviously don't know what markdown is. Markdwon is translated to html, which can then be styled by css. Jekyll (what rubenwardy's sight uses) can automatically convert the markdown files to html. Besides, HTML is unreadable in a normal text editor.

EDIT:
Read this for a better description: http://daringfireball.net/projects/markdown/
Back from the dead!

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Modding Tutorial Book - Creating Better Documentation

by Don » Post

I don't mean this to be rude but maybe start a new topic to debate the best code. This is a thread about the book. Let's discuss the content of the book. I think Rubenwardy could use help.
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

leeminer
Member
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Modding Tutorial Book - Creating Better Documentation

by leeminer » Post

Don wrote:I don't mean this to be rude but maybe start a new topic to debate the best code. This is a thread about the book. Let's discuss the content of the book. I think Rubenwardy could use help.

I've been reviewing the doc and giving feedback. Always helps to have others look at it from another angle.

I think Rubenwardy is looking for translators eventually. Sadly my Spanish and French is dismal :(

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

Re: Modding Tutorial Book - Creating Better Documentation

by rubenwardy » Post

Added a ( (very) short) chapter on ABMs. I will probably write a chapter on node drawtypes next. That's probably the next important thing. I'm also going to draw up a long list of what should be in there, and logically organise it for the best teaching experience.

I don't need it to be translated yet, it is currently quite unstable (it changes a lot).
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Modding Tutorial Book - Creating Better Documentation

by Don » Post

An explanation of why you need to do things would be nice. For example in your formspec chapter you have

minetest.show_formspec(playername, formname, formspec)

If you could explain it like this;

you need minetest because it tells the engine where to get the info
show_formspec tells engine to show the formspec that you specify below
playername is need for...
etc

This is one of the things that confused me at first. I am not sure if the info above is correct or not. As someone who does not know programming and just wants to make mods this type of info is important. I don't think you would have to do it for everything but if you explain some of it then with a little logic the rest could be figured out.
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Modding Tutorial Book - Creating Better Documentation

by Don » Post

Another idea might be itemstack and how it works.

EDIT - forgot to say that you are doing a great job! Thanks
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Modding Tutorial Book - Creating Better Documentation

by Don » Post

Another idea is what different symbols do
Examples

== means is equal too
~= means is not equal too
-- means a comment and is not read by the engine. It is for 1 line only
--[[ ]] means a block comment for more than 1 line
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

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

Re: Modding Tutorial Book - Creating Better Documentation

by rubenwardy » Post

I don't want to do a programming tutorial, that is beyond the scope of the book. I will search for a nice tutorial on Lua. Short.

Hoodedice is creating a getting started chapter which will be a much easier entry point.
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

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

Re: Modding Tutorial Book - Creating Better Documentation

by philipbenr » Post

@Don: That is something I might get into. The tutorials want to do will include videos as well.

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Modding Tutorial Book - Creating Better Documentation

by Don » Post

@ rubenwardy - I am throwing ideas out there simply because I am trying to learn and these are things that I got stuck on. Thought it might help to get the perspecive of someone that wants to learn how to mod.

@ philipbenr - That it awesome. Videos will be a big help too.
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

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

Re: Modding Tutorial Book - Creating Better Documentation

by rubenwardy » Post

the Minetest namespace, ie minetest.*, will be explained in the first chapter, and itemstacks is a planned chapter. I didn't intend to sound like I was rejecting your ideas.

As for videos, they take a lot of effort to get to the same quality, although they are better at communicating harder things that would need a huge and confusing list in a tutorial if done right. Good luck.
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Modding Tutorial Book - Creating Better Documentation

by Don » Post

rubenwardy wrote:the Minetest namespace, ie minetest.*, will be explained in the first chapter, and itemstacks is a planned chapter. I didn't intend to sound like I was rejecting your ideas.

As for videos, they take a lot of effort to get to the same quality, although they are better at communicating harder things that would need a huge and confusing list in a tutorial if done right. Good luck.
I took no offence. I was just letting you know why I was giving ideas. As someone who knows almost nothing about programing I know some of my ideas will be rejected or considered dumb.
Keep up the good work
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

leeminer
Member
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Modding Tutorial Book - Creating Better Documentation

by leeminer » Post

Don wrote:
rubenwardy wrote:the Minetest namespace, ie minetest.*, will be explained in the first chapter, and itemstacks is a planned chapter. I didn't intend to sound like I was rejecting your ideas.

As for videos, they take a lot of effort to get to the same quality, although they are better at communicating harder things that would need a huge and confusing list in a tutorial if done right. Good luck.
I took no offence. I was just letting you know why I was giving ideas. As someone who knows almost nothing about programing I know some of my ideas will be rejected or considered dumb.
Keep up the good work

Find a good tutorial for OOP programming. I think it would benefit you. One I liked was How to think like a computer scientist.

http://www.greenteapress.com/thinkpython/

It would be very difficult to understand modding without this sort of knowledge. For LUA, not sure what the best resource is. I've only scratched the surface on Lua. Perhaps someone could point us both in a good direction for that.

Anyway on with the ON TOPIC discussion ;)

User avatar
Don
Member
Posts: 1643
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Modding Tutorial Book - Creating Better Documentation

by Don » Post

Thanks. After 5 minutes reading I have already learned a few things. I love the open source community. In a world of greed, open source proves that humanity still exists.
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here

User avatar
Gael de Sailly
Member
Posts: 845
Joined: Sun Jan 26, 2014 17:01
GitHub: gaelysam
IRC: Gael-de-Sailly
In-game: Gael-de-Sailly gaelysam
Location: Voiron, France

Re: Modding Tutorial Book - Creating Better Documentation

by Gael de Sailly » Post

Is it possible to make a feature to change the language ?
I could translate it into French.

I really like the project. I've already thought about writing a tuto in French.
I think it's really what we lack : a good documentation in others languages than English.
Just realize how bored we would be if the world was perfect.

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

Re: Modding Tutorial Book - Creating Better Documentation

by rubenwardy » Post

Do you mean computer langauges? You could use a language interpreter written in Lua. Or you can add a new langauge to the core code. But the forner is slow and the latter won't be merged into Minetest, the core devs won't like it. You could use a language like moon script, I think it is called, to translate into Lua.

Or do you mean tutorial language? That's fairly easy, but requires restructuring of files.
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

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

Re: Modding Tutorial Book - Creating Better Documentation

by Evergreen » Post

rubenwardy wrote:Do you mean computer langauges? You could use a language interpreter written in Lua. Or you can add a new langauge to the core code. But the forner is slow and the latter won't be merged into Minetest, the core devs won't like it. You could use a language like moon script, I think it is called, to translate into Lua.

Or do you mean tutorial language? That's fairly easy, but requires restructuring of files.
Rubenwardy, he means translate to another real world language (eg. French)
Back from the dead!

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

Re: Modding Tutorial Book - Creating Better Documentation

by rubenwardy » Post

Okay. So the latter. I won't accept any translations at the moment, as the chapters are too volatile - they will probably be edited for quite a while before they reach a fixed state.
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

User avatar
Gael de Sailly
Member
Posts: 845
Joined: Sun Jan 26, 2014 17:01
GitHub: gaelysam
IRC: Gael-de-Sailly
In-game: Gael-de-Sailly gaelysam
Location: Voiron, France

Re: Modding Tutorial Book - Creating Better Documentation

by Gael de Sailly » Post

I could also contribute to the project, especially about mapgen.

There are the 4 basics chapters, I think we can add more specialized chapters on more complex features (entities, mapgen, treegen, metadata, schematics, …).
I will have a lot of free time the next 2 weeks.
Just realize how bored we would be if the world was perfect.

grey
Member
Posts: 28
Joined: Fri Jan 03, 2014 18:51
Contact:

Re: Modding Tutorial Book - Creating Better Documentation

by grey » Post

This would be so amazing.

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

Re: Modding Tutorial Book - Creating Better Documentation

by rubenwardy » Post

No more linking to line numbers with the risk of them changing.

lua_api.html
Renewed Tab (my browser add-on) | Donate | Mods | Minetest Modding Book

Hello profile reader

leeminer
Member
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Modding Tutorial Book - Creating Better Documentation

by leeminer » Post

Wow, there is a lot of content here now! Everybody look at this so far.

Post Reply

Who is online

Users browsing this forum: Semrush [Bot] and 2 guests