Writing a manual is an art on its own, here're some things that can go wrong:
* if you let 20 ppl write pieces of a manual you get 20 different writing and example styles. For a beginner a consistent style is important.
* examples are often incomplete or only give a single solution. The best example is polling vs events. I think one should use events, it's how the OS works, and it's so very convenient (and not harder to learn than polling I'd say). Yet, a lot of examples use a polling technique. While I'm not saying to drop polling-based examples, event-based examples should be included as well.
* examples might be huge and bloated. Freedom from choice is what a beginner wants, if there are 10 new things in an example source, how do you want the beginner to identify the single new thing the example was meant for? The best example is one that's as small as possible, but not smaller. It should focus purely on the command for which it was written
* examples are often explained in context of a game, they should rather be explained more generic, or at least also with a GUI/application mindset.
In addition, it might be a good idea to include design patterns into the manual and generic programming guidelines. Yes, design patterns are explained on normal wiki, but those examples are not really aimed at Blitz or beginners. I actually don't know whether all those examples actually work in BMax.
* if you let 20 ppl write pieces of a manual you get 20 different writing and example styles. For a beginner a consistent style is important.
* examples are often incomplete or only give a single solution. The best example is polling vs events. I think one should use events, it's how the OS works, and it's so very convenient (and not harder to learn than polling I'd say). Yet, a lot of examples use a polling technique. While I'm not saying to drop polling-based examples, event-based examples should be included as well.
* examples might be huge and bloated. Freedom from choice is what a beginner wants, if there are 10 new things in an example source, how do you want the beginner to identify the single new thing the example was meant for? The best example is one that's as small as possible, but not smaller. It should focus purely on the command for which it was written
* examples are often explained in context of a game, they should rather be explained more generic, or at least also with a GUI/application mindset.
In addition, it might be a good idea to include design patterns into the manual and generic programming guidelines. Yes, design patterns are explained on normal wiki, but those examples are not really aimed at Blitz or beginners. I actually don't know whether all those examples actually work in BMax.