API docs improvements
Posted: Sun Jul 31, 2016 10:44 pm
For reference, current API docs: http://lua-api.factorio.com/latest/index.html
As a newbie modder, I'm constantly struggling to try and wrap my head around where things are in the docs...
1. Provide list of globals which the game adds (game, script, defines, global, etc) linked to relevant docs. This will make it much easier to see at-a-glance what _G globals the game adds, what they do (briefly) and linked to full docs.
2. For each of the docs pages associated with the globals mentioned in (1) above, there should be dedicated docs page to describe that global and what it provides, which context it can be used in (eg. can it be used in control.lua, etc).
3. Ideally add a sidebar nav that makes discovery of documentation easier. Some examples:
* http://sailsjs.org/documentation/concepts/assets
* https://markdown-it.github.io/markdown-it/
* https://github.com/lord/slate
4. Search box with auto-suggest/complete
As a newbie modder, I'm constantly struggling to try and wrap my head around where things are in the docs...
1. Provide list of globals which the game adds (game, script, defines, global, etc) linked to relevant docs. This will make it much easier to see at-a-glance what _G globals the game adds, what they do (briefly) and linked to full docs.
2. For each of the docs pages associated with the globals mentioned in (1) above, there should be dedicated docs page to describe that global and what it provides, which context it can be used in (eg. can it be used in control.lua, etc).
3. Ideally add a sidebar nav that makes discovery of documentation easier. Some examples:
* http://sailsjs.org/documentation/concepts/assets
* https://markdown-it.github.io/markdown-it/
* https://github.com/lord/slate
4. Search box with auto-suggest/complete