BlitzMax HELP is VERY VERY POOR
BlitzMax Forums/BlitzMax Beginners Area/BlitzMax HELP is VERY VERY POOR
| ||
| I absolutely love the Help with all the Blitz Suite of applications apart from BlitzMax it really is poorly defined, lacking in examples and worst of all seemingly hidden from view. One has to dig to find it???? I think the language is fantastic and have always used Blitz since the early Amiga days of Blitz Basic 2 but I really do think the new Help system is shockingly poor. Creating a simple timer and using it with WaitTimer kept coming up with compiler errors, cmon' WTF! It seems everytime I need to use commands that I have used umpteen times before I have to search the net for examples using these commands just to get the syntax correct. |
| ||
| Yeah, there's several other threads already saying exactly the same thing. So maybe people should do something about it instead of reiterating the same problem. As to your timer errors, BlitzMax is NOT Blitz3D and it is NOT BlitzBasic or BlitzPlus. It's BlitzMax, it's a different language, and nowhere is there any claim that it's supposed to have any syntax in common with the other languages. That means you can't expect things to work the same as other Blitz's just because you happened to use them before. The documentation is not terrible, it could be improved and made more detailed and complete, but most people can get by with it. You'd have to post some code about your timer thing for people to help you figure it out. |
| ||
| Stop shouting about it, we all know the docs are dodgy. Typing in all uppercase letters doesn't improve your chances of getting BRL's attention. |
| ||
| Well WaitTimer is in the BlitzMax documentation so I would have expected it to be better explained as it is effectively the same command as previous versions, and as regards to stop shouting we know the docs are dodgy....that response begs belief..... It's like buying a book to learn French and the translations are badly documented if at all. This is exactly the same just a different language. And you say stop shouting, give us a rooftop to shout more from I say. What do you think people should do accept it like good citizens? |
| ||
| The documentation is not terrible It is, in the scheme of things. but most people can get by with it. Yes, those people who have had to fight through the lack of documentation and now have enough of a basic understanding to work things out themselves. You'd have to post some code about your timer thing for people to help you figure it out. Which I think is part of the point. If the documentation was adequate, one wouldn't need to be faced so quickly with having to ask the forum about something so elementary. Anyway, hopefully things will improve, but for now kRUZe, unfortunately you may have to make do with what level of documentation there is, as well as the good resources of the forums. |
| ||
| It's a good thing there are a lot of people in the community to help. A while ago a rather big topic went in to detail on how to use a TMap, which isn't that well documented as well (no examples at all...). But I agree, the documentation could've been a lot better. But so far I've been able to figure it all out. |
| ||
| *sighs* |
| ||
| Tmap is something that especially needs to be documented properly, its a good function and maybe people will avoid it and not even bother to search the forums about it. |
| ||
| My suggestion for this would be to create a sticky topic for each command Here and let people create posts within it... periodically the moderators could take contributions and update the first post with them. Other than that, a wiki is likely the best way to go provided it can be collapsed into an offline manual in some easy way. |
| ||
| "Yeah, there's several other threads already saying exactly the same thing. So maybe people should do something about it instead of reiterating the same problem." Since Blitzmax is a commerical program being sold, proper docs should start at the top. If Blitzmax goes free, then I'm all over a community driven doc project. |
| ||
| Thats actually a good point... of course, its also pretty inexpensive too... Paying to have the docs generated would increase the cost as well... but, proper docs will help sell it.. As would a proper included media package... I'm sure Mark knows whether sales need a boost or not |
| ||
| Replying to thread topic... "I AGREE!" ;) |
| ||
| I don't understand why a few people here feel the need to jump on anyone highlighting a valid problem. This guy is fairly new and may be unaware that the problem has been raised (many times) before. It's supposed to be a beginner's language, therefore it's all the more important that it's documented, IMO. We're not even talking about a high level of documentation, just a simple explanation of each command. |
| ||
| We already have simple explainations of each command, what's needed is a more thorough in-depth approach with better examples and more explaination of why things are they way they are, and how to use them, and for what. |
| ||
| My suggestion for this would be to create a sticky topic for each command Here and let people create posts within it... periodically the moderators could take contributions and update the first post with them. Which is precisley how the old docs system worked for b2d / b3d. The dev team could update the base doc and remove posts on each command, and those docs got zapped back into the official docs. So the entire community could contribute, the dev team could moderate and filter, and it was dead easy for mark to include additions in the official distro. This was a major part of why the b2d/b3d docs were good. The move to inline docs within the code for BlitzMax broke that process, and was never replaced. shame. |
| ||
| Since Blitzmax is a commerical program being sold, proper docs should start at the top. If Blitzmax goes free, then I'm all over a community driven doc project. You're right. Far better to complain loudly and refuse to compromise our "principles" in order to achieve precisely nothing than to put our pride and principles to one side and actually do something to improve the situation. |
| ||
| Why and how is this thread still going? It's basically a titanic argument that's going nowhere. |
| ||
| It's supposed to be a beginner's language, therefore it's all the more important that it's documented, IMO. A beginner's language? I don't think so. Wasn't it you who was selling your BMax recently? I'm sure it was you. |
| ||
| Move along, nothing to see here... :) |
| ||
| Wasn't it you who was selling your BMax recently? I'm sure it was you. ...and that has what exactly to do with this thread? |
| ||
| Oh nothing I suppose. |
| ||
| "You're right. Far better to complain loudly and refuse to compromise our "principles" in order to achieve precisely nothing than to put our pride and principles to one side and actually do something to improve the situation." yawn.... |
| ||
| I remember when I bought my copy of B3D, it came with a manual. What would be the harm in BRL creating a manual in PDF format for users to download. If the documentation is to be created by just reading the special comments in the BMax source code, then they should put a lot more detail in the comments. The documentation is piss poor. It shouldn't be up to BRL to teach us how to program, that's up to us to learn. But they really should give details and examples on how to use their BMax specific commands. TMAP being a prime example. I'd have never known about it if I didn't see the thread about it in these forums. |
| ||
| This was a major part of why the b2d/b3d docs were good. Weren't those funded by their publisher at the time? Since Blitzmax is a commerical program being sold, Wow, that is news. I didn't know Mark had got another publisher. Where can I buy BMax in a retail store? I thought it was just an indie language being sold by indie developer(s) via this site. |
| ||
| I think docs must be exhaustive rather then long. For example see event mod docs: Function EmitEvent( event:TEvent ) Description: Emit an event Information: Runs all EmitEventHook hooks, passing event as the hook data. What about failures or returned values? Function CreateEvent:TEvent(id,source:Object=Null,data=0,mods=0,x=0,y=0,extra:Object=Null ) Returns: A new event object Description: Create an event object What about params description, data format or type? Even without examples, some more MINIMAL information would be useful to avoid wasting time. |
| ||
I define my parameters like this :Rem bbdoc: If the current subpath is not empty, begin a new subpath. about: After this call the current point will be <b>(x, y)</b>. <p>Parameters: <ul> <li><b>x</b> : the X coordinate of the new position</li> <li><b>y</b> : the Y coordinate of the new position</li> </ul> </p> End Rem Method MoveTo(x:Double, y:Double) I suppose something more like the following would be prefered : Rem bbdoc: If the current subpath is not empty, begin a new subpath. param: the X coordinate of the new position param: the Y coordinate of the new position about: After this call the current point will be <b>(x, y)</b>. End Rem Method MoveTo(x:Double, y:Double) Where param list should be in order. Of course, something like javadoc style annotations might be even better - especially for parsing. (like @param etc) |
| ||
| I'm working on a BlitzMax game development book which will be helpful to cover the missing/unclear topics ... but will be a while yet since it's being developed alongside games etc. |
   |