Making Max more beginner-friendly
BlitzMax Forums/BlitzMax Beginners Area/Making Max more beginner-friendly
| ||
| In response to the locked topic, I have some suggestions which might help make 'Max more beginner friendly. Don't get me wrong here - I am very impressed with Max as a language, but presumably BRL want to sell copies to newcomers and users of B3D and B+, and also customers want a gentle learning curve. First things first - the home page is disorganised. Think about the order users will do things in: View the user guide, learn the language, look at the modules, play with the examples. 1. Language Documentation The language docs are very good at explaining the little individual bits of the language, but there is nothing which puts it all in perspective, and no explanation of how various language features are useful in a practical environment, or which features are mainly for beginners, and which relate to advanced users. The language docs often assume an existing knowledge of various features, and seem to focus purely on how BlitzMAX works in relation to other languages. For example, the explanation of what an array is consists of only one sentence, and some aspects, such as what a multi-dimensional array is are barely covered at all. Tech-jargon: Don't use the words 'inheritance' and 'poly-morphism' in the "Users Guide" for example. These are scary words for fairly simple concepts, and are likely to turn people away. The main guide should explain what these are about (without mentioning the "i" and "p" words), and then just mention at the end of the sections that these are the technical terms. The largest omission is a lack of explanation about what exactly object-orientated programming is, why it might be useful, and a clear explanation of the alternative approaches to programming in Max. 2. Module Documentation I think the module documentation is lacking in two main ways. Firstly there is no diagram showing how the modules all fit together in the context of a game. It is not always clear from the names of the modules what they are for - how would I know to look for Input commands in the System module for example? I suggest a diagram on the first page of the reference which contains the key catagories (Graphics,Audio,Data Storage,Input-Output,Input etc) and then shows which modules relate to which sections and how the modules relate to each other. ie. showing that bankstream and ramstream come under stream. Secondly, the introduction to some of the modules is a bit weak. In time a tutorial for making a simple (but all-encompassing) game would be nice from cradle to grave, so to speak. Meanwhile a tutorial for each major module would be very welcome. A five or six line example can hardly cover all the necessary aspects. 3. Newbie Functions I noticed that whilst many of Max's functions are very powerful, there are many important functions that are missing: - No RGB or RGBR,RGBB,RGBG commands for creating colours or extracting the elements of a colour. Needless to say, for anyone looking at the Pixmap documentation this will totally bewilder beginners. - CollideImage is very flexible, but far, far too complicated for beginners. Please add the ImagesCollide function posted on the forums to the Max2D module - Print and Input *always* send to stdout. It would be nice to have Print to be able to route its output to DrawText for example after Graphics had been called (OK, this would not always be desireable, but an option would be nice). - Many types have methods which are not exposed in the global functions also in that module (ie. the functions listed in the module reference), TList.First() for example. It seems to me that the need to have a function which purely wraps a type method is a bit daft. Why not have an alias system where the method would be defined like this: Method First() Alias "ListFirst" Which would allow the user to type "ListFirst listObject" in the code and have the compiler automatically create the wrapper function. |
| ||
| I have huge respect for robert who has managed to completely sum up every problem I'm having with Blitzmax. Spot on. 'inheritance' and 'poly-morphism' scare the hell out of me and I've no idea what anyone is talking about when they lapse into OO jargon. BRL need to LISTEN for a change. Forgive me if I'm wrong but it seems as though they are listening to either just themselves or the wrong kind of people. Surround yourself with experts and most of your market will go elsewhere with poor demo to sales conversion rates. Blitzmax is in no shape or form ready for people coming from Blitz3D or any other language for that matter. It's bewildering to all but a few users on this site. It's nice to know I'm not the only lost soul. The mac version's compiler and modules are the only things out of beta. A product like this is so much more than the compiler and modules. Documentation and presentation are equally important. These aspects have been grossly overlooked. Imagine a paint package that uses cursor keys as the default input and you have to mess with a config file to enable the mouse and this is undocumented. Thats the kind of impression Blitzmax gives me. |
| ||
| Robert, well done, you put a lot of the problems I'm having as a beginner into words better than I can :) |
| ||
| I think some of the changes between BlitzMax and the older versions of blitz should be highlighted more... For example, something extremely basic that I couldn't find anywhere in the documentation: How do you enter multiple commands on a single line? It used to be seperated by the : but that is no longer the case. Through trial-and-error I found that it has been replaced by the ; in BlitzMax. I checked all the obvious places in the documention: Overview, Basic Compatibility, Program Flow, Management.... Zilch. None of the samples I saw included more than one command on a single line either. (Great for simplicity's sake of course, but a pain in the neck when you are actually trying to find out something as dead-simple as what the : actually has been replaced with in Max...) |
| ||
| The language is not hard at all. I think bmax is shaping up really well, as long as the bugs/feature requests/modifications don't get ignored, the v1.0 for pc should be great. Unfortunatly as usual, some of the obviously simple, but needed/wanted functions don't exist in the command set. What is up with no RenameFile function ? Not in b+, b3d and now not in bmax. It has been requested on multiple threads for all versions of blitz. That is just one example, the RGB functions mentioned above are another. I understand the "keep things simple" idea, but leaving out functions that would be simple for mark/skid to add, yet extremely hard for a novice. It just makes no sense, why not extend the language with a larger variety of functions/commands so that everyone is happy. Even if some wont be used by 1 person, its not to say that the next person will need said function. I dont find the language daunting or anything, it is just tedious having to try and guess how things are working. I think the docs explain the basic function of a command, but they dont go onto explain what it DOESN't do, how it works or the advanced functionality. |
| ||
| Thats you, I find it pretty daunting. Everyone will be different and that should be respected as well. See the docs sticky for some gotchas already arising that should have been documented, and clearly. I believe a FAQ is a good idea, and some people miss the point by saying "it's in the docs..." but a FAQ is about common questions asked, docs or no. |
| ||
| Totally agree that a "what you need to know" document is needed for people migrating from previous versions of Blitz. I suspect the reason for this omission is down to BRL expecting most of the initial buyers would be newusers on Mac, not migrating PC users. Hence it was likely deemed not particularly important for the Mac release. As it turns out, many existing users have bought max, at least in part due to the (possibly too early?) release of the BETA versions. They definitely need to create this document for the proper release of max on PC, and may well have every intention of doing so. BlitzSupport's thread is evidence that they were aware of this very issue from the off, that thread just needs to become part of the documentation. I would also appreciate a better means of working out what functions are in which modulea, although I'm not sure I can think of a really good answer to that problem. An overview diagram as suggested would be an excellent start. Full text search would also help immensely. |
| ||
| I agree that the documentation seriously needs to be improved. But I can't imagine making BlitzMax any more newbie friendly than it already is now. I hope the language stays exactly how it is and just better documented. |
| ||
| The language is not hard at all. I think bmax is shaping up really well, as long as the bugs/feature requests/modifications don't get ignored, the v1.0 for pc should be great. I have no qualms with the language itself, just the docs. |
| ||
| I think the docs should be broken into "regular" and "advanced" sections, with all of the OOP-stuff put in the advanced section. OOP just confuses a beginner, and tends to make newbies write horrible code. Same goes for pointers. |
| ||
| Yeah same here, it's the docs that aren't great for a newbie. It takes a lot of experimentation and pouring over other blitz language examples to get an idea what something does and how to use it. The doc's currently have a technical description of what a command does, and doesn't give examples that explain what the command is for, except in what seems to a newbie an abstract fashion. Like looking at a cubist painting for the very first time and and wondering what kind of gras the guy that made it was smoking. But when you know what it's all about its pretty simple really. Thats how I find Bmax at the moment, and its all down to the docs. |
| ||
| I still can't work out how to resize multi-dimensional arrays or how to create arrays of arrays so I can slices on them to achieve the same thing. Not suggesting they be removed, simply the docs have some example code for both. Also function pointers and object casting/management could all do with in-depth info, as I'm constantly having to write test programs just to work out how things work..which means I could be missing a better way. The docs should cover the pros and cons.. |
| ||
| Thinking back to, for example, how comprehensive the docs for Amos Basic were, I think there is some room for improvement. But then again, those were written by a dedicated person who had a nack for it. Not saying BRL doesn't have a nack but at the moment there are too many assumptions of preknowledge and not enough bigger picture awareness. |
| ||
| I had amos and blitz on amiga, and both were better documented than this. I am winning the fight, but I guarantee a lot of potential customers are going to turn the demo down if they don't have immediate documentation answers. Even hitting F1 twice in the IDE isn't properly documented. The IDE is the first port of call. |
| ||
| I still can't work out how to resize multi-dimensional arrays or how to create arrays of arrays so I can slices on them to achieve the same thing. Arrays of arrays: Local q:Int[][] q=q[..10] q[0]=q[0][..5] q[0][0]=42 Print q[0][0] I haven't been able to resize multidimension arrays as yet (not without losing all of the contents of the old array or having to copy each element across one by one) |
| ||
| I haven't been able to resize multidimension arrays as yet (not without losing all of the contents of the old array or having to copy each element across one by one) I don't think you can resize UP without losing the contents, just resize down by 'slicing' the array as above. I guess one could write a simple ReDim command using a memcpy... |
| ||
' Declare an array of array Local q:Int[][] ' Size array 1 of one element q=q[..1] ' size array 2 of one element q[0]=q[0][..1] ' Init element [0][0] q[0][0]=1 ' Print element [0][0] = result 1 Print q[0][0] ' Now we resize array 1 to 2 elements q=q[..2] ' But we need also to resize array 2 of element 2 of array 1 to 1 element, humphhh..... :) q[1]=q[1][..1] ' Init element [1][0] q[1][0]=10 ' Print element [0][0] and [1][0] Print q[0][0] ' Result 1 Print q[1][0] ' Result 10 |
| ||
| This is an excellent thread. Robert did a damn good job in his first post. Well done. |
| ||
| I agree in most points, but words like 'inheritance' and 'poly-morphism' should be used. If you have beaten your fear and got it, you will be happy to know the words meaning if you later switch to another language or discuss a problem with guys which dont own BMax. Maybe its me but later i found it very hard to replace already learned terms for concepts with the common used terms. |
| ||
| What Robert said was to make sure while explaining the concept to the user, not to use these words and then after the tutorial is over, to -then- bring up the technical/common used terms for that and which term is used most within the Blitz community itself. I think that's a good idea... |
| ||
| I see, i agree. And please write some lines about why you would use something like inheritances. Its much easier for beginners if they know what they could do with something like. I always have problems remember new things, if i dont have a clue for what they are good for. Anisotropic Filtering..hehe... |
| ||
| What Robert said was to make sure while explaining the concept to the user, not to use these words and then after the tutorial is over, to -then- bring up the technical/common used terms for that and which term is used most within the Blitz community itself. I think that's a good idea... Sounds like those awful education techniques used by some schools in the 70's (I nearly went to one) where they taught kids to read and write phonetically and worried about spelling years later; Thus dooming thousands of kids to semi-literacy. They are only words - no point in hiding them away. |
| ||
| Real-world examples are always good. |
| ||
| Sounds like those awful education techniques used by some schools in the 70's (I nearly went to one) where they taught kids to read and write phonetically and worried about spelling years later; Thus dooming thousands of kids to semi-literacy. It is nothing like that at all. All I am saying is that programmers need to know, for example (with inheritance): - That types can extend other types - The syntax for declaring a derived type in Blitz - Why it is useful - Real-world applications of this - Problems and pitfalls that programmers may encounter The associated lingo is only useful once the programmer understands the concept in the first place. When teaching something, I find it is always best to use terminology that people already understand. |
| ||
| They are only words - no point in hiding them away. Thats fine, but a good way to learn is to teach us what they mean. The docs don't even do this.And of course teach us in stages. It surely couldn't have taken more than two days work for a guide on OO to be written up as a tutorial for blitzmax. I understand a lot of people might feel defensive if I critictise, but at the end of the day I feel it's constructive. |
| ||
| It's more constructive to do something about it. Why not help out by contributing to the BlitzWiki. |
   |