I have some free time, so here's some free answers.
Do you feel as though the documentation is lacking in any ways?
One thing I found very lacking when trying to use AppGameKit the first time is examples of what happens to the "data", "memory", or "display" for the commands.
The issue is the manual assumes the commands will work out of the box. (They usually do but most require other commands to setup things in memory beforehand, which isn't always explained very well). The manual then leaves it up to the user to see what the result is, or in most cases, to figure out HOW to see what the result is.
I also think a lot of the graphical, file accessing, and text display examples would benefit greatly by including "before and after" like screen shots. Or in the case of the file accessing, screenshots visually showing what the engine is reading/writing in an example file.
Then a new user could compare the result they are getting with the manual's expected result to more easily figure out what they are doing wrong. These screenshots showing how the data is being processed visually would also help remove some of the ambiguity of commands such as the file/line reading commands, graphical shader effects, or string processing operators.
Would we benefit from having tutorials covering specific functionality?
The manual would, yes. I would love to see some examples of multiple command "systems" like loading a level's "blocks" from a file, for example. A lot of the current documentation focuses on a single command at a time, which is great for learning the commands. But then it leaves connecting them almost entirely up to the user. Which can be very daunting to someone not versed in how to "think in game code".
One issue I ran into when using AppGameKit for the first time is the lack of documentation on "best practices". It would be great to have some "best practices" articles for mid level concepts like creating a "game loop", iterating over image slots, creating input control globals that can be read by the rest of the game code and when to update them, using multiple script files to keep a game's code and objects organized, and so fourth.
Would it be useful to have guides showing how to make simple games as a way of getting started?
It would be useful, but I would be careful to not make them too detailed. A recreation of asteroids with lots of multiplayer features sounds like great practice on paper. But a simple "here's a ship and some asteroids that wrap around the screen" would be more useful to a new coder. New coders do not want to make billions of options for an asteroids multiplayer game just yet, they just need to know how to get their hero to load up and move about the screen.
For example, the asteroids game could focus on basic sprite rotation and movement/input techniques, leaving expanding the game up to the user from there. A separate game could then focus on multiplayer networking and syncing the game state, or on making an options menu, and so on. I think small games that focus on good coding practices for part X of the game would be much more useful then full blown games. The tutorials would also be shorter and easier to follow that way.
Might the documentation benefit from many more examples showing how to use specific commands?
There's a few places it might help, as many of the same examples are just copied over many different applicable command pages right now.
One big gap is the shader, lighting, and texture commands. They tell exactly what they do, but don't provide any screenshots or best practice info on how to get good results. With how much time it takes to set up a testing environment for lighting or make shading materials, a screen shot and best practice bullet point would go a long way to helping teach newcomers how to do 3D or shaders the "AGK way". Or what they should be expecting as the results.
The mobile focused commands are also woefully under explained. The current approach requires lots of hours invested into making a test mobile app and trying out all the different commands. Once again, it would be really nice to "know" the result of commands by reading/seeing it without needing to try them myself.
Would the addition of video tutorials be helpful?
It wouldn't hurt, but should not replace the text manual. As AppGameKit is mostly a code focused development tool, I think it's more useful to read the text and type commands at our own pace then to try to follow and pause a video. One place videos would shine though is in showing the results of tutorials or graphical commands, so users can confirm they did them right or are getting the correct result. And of course a few rare visual things would be better explained in video. But please include text explanations too, for those with slower internet connections!
For an example of doing this wrong, look at Unity's all video concept lessons, which are very helpful, but I try to avoid needing them because my internet is not stable enough to watch the videos on high quality.
(I love Unity otherwise, but sometimes they do silly things and forget we don't all have high speed internet yet.) So always remember that some users will not have video capability when viewing your documentation.
For a beginner do you feel the documentation is adequate?
It's adequate IF the beginner has had previous coding and video game structuring/logic experience. However to a complete new user, it is severely lacking in best practice knowledge, which could get them "boxed in" to bad code structure later in development. Anything that helps minimize long term "traps" like this for new users will help them be more effective in using AGK.
Are enough advanced topics covered?
I would like to see a few guides on structuring game loops and using multiple script files effectively. These are not "fun" things to try to figure out on your own, and it's easy to affect game performance by mistake simply by structuring your basic game loops or loading resource code wrong.
Another topic not covered well is good practice for making games support "options", like rendering resolutions, lower graphic settings, or even dynamically changing the resolution and controls to match mobile or desktop. A tutorial or guide giving some concept examples of how to go about coding such "bread and butter" features could help newcomers and pros alike add that "extra polish" to their games.
