Wuzzy wrote:You are completely missing my point.
Eye candy does not matter when the content is wrong.
You are only talking about visuals, I am talking about content.
It's more about convenience than visuals. Like being able to click on "itemstack" to get to the definition of the class, instead of doing a file search.
lua_api.txt is written in Markdown syntax, so can be parsed and pretty-printed automatically by scripts, see rubenwardy's example. Maybe a pretty-printed version of lua_api.txt should be included in the repo as well. Theoretically, it could even be parsed to generate wiki pages, although that doesn't really make sense to me. Plain old HTML would make more sense.
Yet, when someone sees the documentation is lacking on some point, you have him or her to make a pull request. If you compare side by side Github and a Wiki, that's three steps versus two from scratch (github: register account, clone the repo, make pull request; wiki: register account, edit the freaking page). And here, I overlook the tiny little detail that the poor soul may have to learn git in the process (some won't, some will but also will forget what they were doing and some will ascend to the astral plane and just to throw that freaking amulet at your face).
Have someone here heard of the concept of "path of least resistance"?
Maybe a pretty-printed version of lua_api.txt should be included in the repo as well.
So what is recommend there is either:
- have people use an extra tool to get a decent-looking documentation, which sucks
- or include an auto-generated file in a git repo, which is bad practice (granted, it won't set the repo on fire, but still)
I'll leave here for reference the "developer Wiki" of another FOSS game, Oolite:
http://wiki.alioth.net/index.php/Oolite ... ject_model