Page 1 of 6

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

PostPosted: Thu Dec 11, 2014 19:44
by rubenwardy
This online book will (eventually be able to) teach you how to create mods in easy chapters. The chapters will explain a concept, give examples, and set tasks for you to complete.

This documentation was created by the Minetest community in order to help new modders gain a foothold.

Work in progress. I'd like suggestions for contents. What chapters would you like to see?

Read it online - Download

Contribute on GitHub, or by sending me documents for new chapters.
(I'll format them and add them, the content is the hardest thing, not the formatting.)

Done
  • Folder structure
  • Lua Scripts
  • Nodes, Items and Crafting
  • Creating textures
  • Node Drawtypes
  • Node Metadata
  • Active Block Modifiers
  • Chat and Commands
  • Player Physics
  • Formspecs
  • HUD
  • ItemStacks
  • Inventories
  • Releasing a Mod
  • Read More

Todo
(please feel free to work on any of these, or any other chapter you want to do)
  • Entities
  • Particles
  • Sound
  • Mapgen and LVM
  • Organising code - patterns
  • ...

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Thu Dec 11, 2014 20:01
by ExeterDad
You are to be worshipped from this day forward.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Thu Dec 11, 2014 21:57
by philipbenr
Hmmm. I think that I might just do one with pure html and css. It would be nicer and easier for most people to make.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Thu Dec 11, 2014 22:04
by rubenwardy
Philipbenr, yeah no. Markdown is easier to create, you can still get html exports. I'll start making them when I get more chapters.

Markdown is human readable, so makes sense as plain text.

You can just write chapters as a text file in chapters, and I will link and correct formatting. You never actually need to use Jekyll. Feel free to submit a word document. Writing is the hard bit, not the formatting.

Jekyll allows you to include other HTML files. Much easier.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Thu Dec 11, 2014 22:40
by Evergreen
THANK YOU

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Thu Dec 11, 2014 23:06
by leeminer
I wish I had more thumbs.. two thumbs up!!!

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Thu Dec 11, 2014 23:16
by philipbenr
Truthfully, I find markdown confusing and html more organized. More complex, but more organized.

Edit: Plus, with css, I can do some really amazing effects, plus make a popup of pure css(3?) (strange, huh?) It would be harder for a person to add to it, but it would be easy for some web developers. Personally, when I used markdown, it took more memorization than html. There were div (dividers) and p (paragraph) and h_ (header, size _) and the like. It is different with different versions of markdown, but I find html easier to memorize.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Thu Dec 11, 2014 23:30
by leeminer
For those who don't know what markdown is. Like me.

http://en.wikipedia.org/wiki/Markdown

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 07:28
by rubenwardy
Anything is confusing if you don't put any time into learning it. The tutorial is supposed to be written by authors, not web developers.

You can use HTML in markdown. Markdown isn't hard. Popups are not needed.

BTW, the HTML is in _includes/header.html and _includes/footer.html.
CSS is in static/style.css

I don't see your point.
These are really the only things you need:
(Plus images)

Code: Select all
Section
-------

Here is some text

### source code
    Code snippets are
    Tabbed one level in.

Another paragraph

* one
* two
* three

[Link](http://URL)

<b>this is perfectly valid<\b>


The tutorials should be printable, in theory

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 12:18
by srifqi
+1

I don't know which is better HTML or Markdown, for me it's same.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 12:50
by Linuxdirk
rubenwardy wrote:Markdown isn't hard.

Markdown is easy as pie :D

srifqi wrote:I don't know which is better HTML or Markdown, for me it's same.

For content … Markdown is better.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 14:49
by philipbenr
Okay, I just want to say, I do see your point, but this is what I was talking about when I said you can do cool stuff. There is no javascript involved in this whatsoever. You can hover on the quote slider to stop it, and you can hover on the cards to make them zoom, (Also, sorry about the cards. I was lazy, so I just did a quick fix and put them in a table. I should just change a couple things around and fix that to be normal for all zooms and displays. Same with the height of the quote slider. But still. There is a lot of cool stuff in there, isn't there?)

Re: Minetest Tutorial Book - Creating better Documentation

PostPosted: Fri Dec 12, 2014 15:28
by rubenwardy
1) you can do that with my markdown thing. CSS can be used, so can HTML.
2) it's not needed for this project.

I do like CSS, although it is a pain when doing columns or mixing fixed and %.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 15:39
by leeminer
To tell you all the truth, if you told me the tutorial Rubenwardy made was a text file without HTML markup I would have thought you were crazy.

The point of a tutorial isn't fancy CSS or HTML or javascript, the point is to show examples, and tutor people with info. I find the format and style super easy to read. We should focus on the content I say.

Rubenwardy, let us know what we can do. Like I suggested before, maybe we start an FAQ and add that to your documentation some how?

What does everyone think of an FAQ idea. For a noob to minetest like me, a FAQ would be greatly helpful, and in conjunction with the tutorial really great.

Maybe even a FAQ for each chapter?

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 15:43
by rubenwardy
I would like to add 'tip' and 'watch out' boxes. This online book will be in the similar style to a teach teach yourself in 24 hours style book. FAQs will be talked about in the paragraphs.

I would like a list of possible chapters, and suggestions on what common mistakes and problems are.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 18:31
by Evergreen
I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 19:14
by leeminer
Evergreen wrote:I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.



Visually its kind of blah.. Trying to define blah, not much color or variation or anything to draw your eyes to where they should go.. if that makes sense.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 19:15
by Evergreen
leeminer wrote:
Evergreen wrote:I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.



Visually its kind of blah.. Trying to define blah, not much color or variation or anything to draw your eyes to where they should go.. if that makes sense.

I'm not giving it as an example for color, I'm giving it as an example for content.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 20:12
by rubenwardy
Added a chapter on registering nodes, craftitems and crafting. Next I will be doing formspecs.

You can download a zip of the website here: https://github.com/rubenwardy/minetest_doc/releases

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 20:17
by Evergreen
By the way, here is where you can contribute: https://github.com/rubenwardy/minetest_doc

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Fri Dec 12, 2014 20:35
by leeminer
Rubenwardy,.. perhaps add a link in your signature to the Tutorial. Would make it easy for us to review it... I'll check the update and give some feedback when able today.

Thanks man..

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Sat Dec 13, 2014 18:09
by Don
I am looking forward to the formspec chapter. I have put my millwork mod on hold until I figure out how to make a couple machines for it.

One thing that I have trouble with is knowing where to put things. I am not a programmer. In some mods there is code before the node definition and in others it is in the node definition. A chapter on the code structure would be nice.
I learned a little about ipairs and tables. I haven't found much info on how to use them. I am learning from other peoples mods. I would love to learn more about them.
Thank you for doing this book. I means a lot to me and I am sure many other people.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Sun Dec 14, 2014 08:14
by Zeno
I'd prefer LaTex before HTML/CSS. Markdown is easy and it's probably easier to get others to help if it's easy to do.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Sun Dec 14, 2014 09:11
by rubenwardy
Hi Don. The formspec chapter will be the next I write - you should expect it in the next 48 hours. I will write a chapter on code organisation. It is a great idea.

Re: Minetest Tutorial Book - Creating Better Documentation

PostPosted: Sun Dec 14, 2014 12:27
by Linuxdirk
Zeno wrote:I'd prefer LaTex before HTML/CSS.

LaTeX is awesome in it’s field of work but rather not in the web publishing section :) I’d prefer LaTeX over anything else when I want to create text I want to print or publish in PDF form.

Zeno wrote:Markdown is easy and it's probably easier to get others to help if it's easy to do.

Markdown is more or less “natural writing”. You have little to no syntax elements for parsing except the ones you need to add anyways to structure the context itself (lists, headings, etc.).