Sorry, BRL, you have an EXCELLENT product here, worthy of much respect, but your documentation stinks
Could not agree more :) Is there someone here who considers themselves an 'advanced' user (who is also perhaps somewhat familiar with writing clear/concise/thorough documents) that would be willing to write a totally KICKASS official documentation?
I may not be the perfect candidate but I'll answer the call.
I do not consider myself an advanced BlitzMax programmer, however if it is relative and compared to someone entirely new to game programming and BlitzMax, then very much so ;)
About writing clear and concise, I do not think I can judge that myself. The beginners guide I wrote was not for beginners to programming, it was for beginners to BlitzMax, which I know have caused some confusion. And it got much longer and much more advanced than what I initially intended it to be.
I would be willing to write a totally KICKASS official documentation. I see nothing wrong in doing that, if it would actually be Kickass (if I wrote it without anyone to review it) that is another question.
Why do BRL intentionally ignore the fact that the docs is not that good?
I think it is something like this…
After working on BlitzMax for a very long time it was finally released. At this point they had to write some basic documentation, some of it had already been written while coding. When finally "done" they realized they could work months on just adding examples and improving the documentation's layout and design. Docs is not the most fun part of application development, so it was never done. New features and bug fixes was what the time went to, and still does. And as long as BRL do not desperately need more $$$ they have no reason to make Blitzmax more appealing to more people (like beginners or improving the information about blitzmax at sales), there is still plenty of b3d users who do not have max, and many of them will likely get it once the 3D module it out. By then BRL could keep working on new ideas, and the need to improve the documentation will be last priority again.
They have done a few things to lessen the burden on the docs.
1. open source
2. A tutorial forum
3. A link to the wiki.
I think it is a bit sad that this is where it seems to end.
I can not know if there is any truth in my story above, I'm only assuming something like that is the case, or what do you think?