Lack of documentation: kind of annoying

BlitzMax Forums/BlitzMax Beginners Area/Lack of documentation: kind of annoying

pistacchio(Posted 2009) [#1]
I've read here and there how sometimes mediocre products get attention and users because of a large base of documents, code, dedicated community.
One example may be PHP, an unelegant, sometimes gross and messy language with a very large documentation full of examples, caveats, use cases and tons of code snippets and user submitted classes and stuff.

Now, years ago i bought BlitzBasic. I loved it. I had the boxed version which came with a fine manual and the IDE documentation was good. A working example for every command, iirc.

Three days ago I bought the elecronic version of BlitzMax. I think it is a better language by orders of magnitude: a useful, easy to work with wrapper on C in the form of a very user friendly Basic dialect. It runs fast and I'm using it on Linux. I've already compiled stupid samples programs on Windows too.

What I really find annoying is the documentation. The program itself is provided with a ridicolous doc base. I wasn't able to get a description of Stric vs SuperStrict, I had to look through some tutorials and BlitzWiki. What does the documentation say about it?

SuperStrict: Set SuperStrict mode.

Hmm.. how clever.. Thank God it is specified, I thought it was for disabling comments.

And TMaps. What is a TMap (reading from the documentation)? Who know. Let's see the methods.

Function CreateMap:TMap()
Returns
A new map object
Description
Create a map

This is so enlighting. Nowhere is written what a map is, but at least the documentation is kind enough to clarify that the method CreateMap, guess what, creates a map.

So, finally, Am I missing something important, like an updated documentation, a documentation center os something, or this is a wonderful product, often updated, but with authors not interested in rendering accessible the functionalities of the language itself? How do you handle the lack of documentation?

Thanks.


Jesse(Posted 2009) [#2]
Hi Pistachio welcome to the world of BlitzMAx documentation. I don't know how well you did your research before buying Blitzmax but it is a well know fact throughout the programming communites that Blitzmax's has really bad documentation. The best I can help you with, is to tell you that this community is really helpull and supportive of memebers. If you have a question about something, you can put a search in the forum page. If that doesn't turn something to your satisfaction, ask a question in the relevant forum. Someone will be nice enough to help you.

There are several tutorilas in the Blitzmax's tutorial forum. a few of the best tutorial links are:
http://www.blitzmax.com/Community/posts.php?topic=42519
http://www.blitzmax.com/Community/posts.php?topic=59233
http://www.blitzmax.com/Community/posts.php?topic=59509

also the user created documentation page for members:
http://www.blitzmax.com/bmdocs/topics.php
not complete but may still be usefull.


Nate the Great(Posted 2009) [#3]
I agree with the maps stuff, I never got that completely but the lack of documentation is made up for by the very welcoming and friendly community, as well as the code archives which have thousands of examples (if not millions) of every command and every way to use it.

If you have a question for example the Tmaps question then just search this in google:

tmap site:www.blitzbasic.com

and it will find lots of people who have asked the same questions and possibly examples in the code archives.

I found this almost instantly

http://www.blitzbasic.com/Community/posts.php?topic=59585

which completely explains it
on the rare occasion that you cant find anything, just make a post and be specific. :)


GaryV(Posted 2009) [#4]
What I really find annoying is the documentation.


I find posts complaining about the documentation annoying.

BlitzMax is not aimed at complete beginners. There are plenty of tutorials and there are at least two books on BlitzMax.

If you lack the fundamentals, one of the "Dummies" books on BASIC should help.


pistacchio(Posted 2009) [#5]
Hi Gary,
I'm a professional developer and I've been for the last years (say 10). Not being BlitzMax the first programming language to come on my monitor, I'm not used to think at a compiler like a software to reverse engineer just to discover what is the return type of a function, or, for example, discover by trials and errors what the designer of the language meant by "map" (a hash indeed).

When I buy a compiler I expect that it comes at least with a complete, usable reference, not that it relies on third party books or community provided content for it to be fully usable by the costumers.

That said, could you please tell me what are the books you make reference to? Mind that I'm not really interested in books on programming or books on beginning game development as, if i have to skip 3 chapters where for loops are explained and 2 chapters where concepts like "movements are indeed sequences of static images", it would prove pretty useless to me.

That's also the reason why I was not complaining for the lack of a helpful community or tutorials, but about the lack of a simple yet handy and complete language reference.

Thanks again for your time.


pistacchio(Posted 2009) [#6]
By the way, I am sorry if I sounded unpolite. I'm a big fan of BlitzBasic, I loved it on the Amiga and I like its resurrection. BlitzMax is really different and, to me, better. I just find it a shame that what could be a really excellent language is "only" an excellent language where, to me, the lack of a proper documentation is the what takes the "really" away ;-)


GaryV(Posted 2009) [#7]
When I buy a compiler I expect that it comes at least with a complete, usable reference,


There is a trial version of BlitzMax, you know what you were getting when you bought it. There is no need to complain about it after buying it.

what are the books


Games Programming for the Absolute Beginner with Blitzmax

Game Programming for Teens Third Edition

The above links were found using the wonderful search feature of the forum.
You can search to find the tutorials, and you can explore the online manual.


GaryV(Posted 2009) [#8]
pistacchio: I was a little hard on you, but for perspective, we have had a lot of "newcomers" posting new "bugs" in products that have existed for 5+ years and have been used to make and sell hundreds of games.

Keep in mind that BlitzMax is an indie language. Even Microsoft quit including printed manuals with their languages around version 5 or 6 (I never owned VS 5, so I don't know if it included manuals or not. I know version 4 did and version 6 didn't.).

The manual for BMax may not be the best, but it is certainly better than many of the competing languages. Where the manual lacks, you will find an extremely helpful community. ;)


ImaginaryHuman(Posted 2009) [#9]
The documentation isn't terrible, it's pretty okay in most areas but could be better. There are a few areas that are really poor, like the map thing - which is a tree not a hash table - but most of the stuff that IS defined is quite clear, but for a general lack of detail. That's why people write books about this stuff.


degac(Posted 2009) [#10]
What I really find annoying is the documentation.

Consider this forum (and the people) like an 'extended documentation' - the best help engine you can find!
Welcome on board!

PS:

to be honest the site has an online documentation for the languages (B+, B3d and BlitzMax).
http://www.blitzbasic.com/bmdocs/command.php?name=CreateMap&ref=goto

So ANYONE can add examples, hints, better explanation and comments to make things better...


Warner(Posted 2009) [#11]
That CreateMap description sounds like a placeholder text. Maybe Mark was tired after documenting 3 languages?
Wouldn't it be possible to allow the community to make (small) improvements on the docs?


plash(Posted 2009) [#12]
Wouldn't it be possible to allow the community to make (small) improvements on the docs?
The problem is getting them in the official release.


Htbaa(Posted 2009) [#13]
One could always create patches and send them to Mark. I'm sure he's able to apply those patches.


N(Posted 2009) [#14]
I'd only consider writing new documentation if bbdoc was scrapped in favor of something less painful to use.


Warner(Posted 2009) [#15]
Perhaps an editor that both imports and exports bbdocs?


GfK(Posted 2009) [#16]
Yep, the documents are a bit lacking in many areas. Fortunately, there's plenty of experienced people on the forums who can normally give you a straight answer fairly quickly.

Oh, and I asked the same question about TMaps last year. There's a big long thread about it somewhere. [edit] here.


Who was John Galt?(Posted 2009) [#17]
a useful, easy to work with wrapper on C in the form of a very user friendly Basic dialect
Why do so many people assume it's C behind the scenes?

Yeah the docs are the weakest link for Blitzmax, IMO. I don't know why a few people get so uptight when newcomers mention this issue.


N(Posted 2009) [#18]
Why do so many people assume it's C behind the scenes?
Probably because a few of the modules have some C source in them. Beyond that, it's anyone's guess what they think they're talking about.


Mahan(Posted 2009) [#19]
I think the documentation vs. the $80 USD price tag is completely acceptable.

Before i bought BlitzMax i tried out the demo and i read through nearly all the documentation (help files) the first evening in pure curiosity.

I remember prying into the lib-sources during the first week and looking at how they actually used the OO-concepts but wrapped them in accessors functions to allow easy usage for people that didn't know/want OO.

Like the TMap you mentioned I just looked at the class and I saw is was a normal lookup map with keys and values right away from just reading the method-definitions.

If you want a professional modern compiler with first class documentation look into Visual Studio Professional/Acrhitect, but then the price is about $1500-3000. This is the usual price for modern programming environments for professional usage. (There is an free, "express"-edition but the license makes it more or less a demo-version as I don't think you can release commercial software written in this edition)

BlitzMax price tag very clearly makes it a hobbyist language, and as such I don't expect a DVD-full (or 20+ books) of docs.

On the other hand I've come to appreciate both BlitzMax and Blitz3D for their stability and the language "predictability" (easy to understand and learn). The development of new language versions goes in (relatively) slow iterations but generally the quality of new functions is very good.

And $80 for the full version with royalty free distribution of any commercial apps you might create is superb value for the money imho.

(And BTW: If you are a professional developer, and you are used to having a good code/project-ide/editor you might be interested in the BLIde IDE.)


Who was John Galt?(Posted 2009) [#20]
Nobody could argue that Max isn't a great deal at $80, but that doesn't mean you shouldn't expect a half decent level of documentation.

BlitzMax price tag very clearly makes it a hobbyist language, and as such I don't expect a DVD-full (or 20+ books) of docs.
I would imagine many others, like myself, are drawn to hobbyist languages for ease of use. They don't want to trawl through library source to see how a function should be used. You take your argument to absurdity when you mention 20+ books full of documentation. I don't think anyone would expect anything like that with Blitz. But a few more lines of explanation and at least a single example should not be too much to ask for any function.


Brucey(Posted 2009) [#21]
They don't want to trawl through library source to see how a function should be used.

Very true. And TMap is a good example of something that probably needs thorough explanation with plenty of little examples.

I think the documentation vs. the $80 USD price tag is completely acceptable.

I can't remember how much I paid for the Amiga Blitz Basics, but the manuals with those where generally very good (content wise). Lots of description with useful examples.

The general level (or lack of) documentation does bump up the expected requirement level of the developer, imo. Even as a someone who codes in many different languages for a living, I still had to fumble around a bit to get a hold on some of BlitzMax's functionality. With better documentation I know I would have taken less time to get into it.

I try to make up for it by ensuring my own stuff has at least some basic helpful texts and examples.


Mahan(Posted 2009) [#22]
@John Galt

You take your argument to absurdity when you mention 20+ books full of documentation.



Am I? Look at the following link how many books where included when you bought Microsoft Visual C++ during the 90'ies and early this century:

http://www.emsps.com/oldtools/mscppv.htm

It's not like VS2008 doc and libs are any smaller today than they where back then, they just indexed it all up and made it more accessible in electronic format.

@Brucey:


I try to make up for it by ensuring my own stuff has at least some basic helpful texts and examples.



You are absolutely right about this. I've learned quite a few things by looking at your code myself, and especially your examples are plenty helpful, when checking out all the great goodies you've written (and modularized).

Personally I think reading code and changing and tinkering with it is the most effective way to learn programming a language, but maybe that is not so for everyone.


Besides all of the above I think that this "lack of documentation" is actually a great opportunity for anyone (that takes the time to learn the language) to write a book or two.


Who was John Galt?(Posted 2009) [#23]
I meant it's absurd to suggest that anyone on here was expecting a 20+ books of docs on Blitz, when all they're asking for is a little more than
SuperStrict: Set SuperStrict mode.

Hmm.. how clever.. Thank God it is specified, I thought it was for disabling comments.

And TMaps. What is a TMap (reading from the documentation)? Who know. Let's see the methods.

Function CreateMap:TMap()
Returns
A new map object
Description
Create a map
There exists a middle ground.


GaryV(Posted 2009) [#24]
The great thing is if you don't like BlitzMax, you don't have to use it.


Gabriel(Posted 2009) [#25]
If you want a professional modern compiler with first class documentation look into Visual Studio Professional/Acrhitect, but then the price is about $1500-3000. This is the usual price for modern programming environments for professional usage. (There is an free, "express"-edition but the license makes it more or less a demo-version as I don't think you can release commercial software written in this edition)

This is completely untrue. The Express Editions may all be used for commercial use, and it says so right in the VS Express Editions FAQ Page. Of course, the Express Edition compilers are all considerably more optimized than BlitzMax, and they're decidedly not cross-platform, so it's a pretty odd comparison in the first instance.


degac(Posted 2009) [#26]
I think this is the nth discussion thread about Bmax documentation/lack of it/not adequate/wiki & so on...

Documentation for Bmax is (mainly) 'inside' the modules.
Possible solutions (already said or tested) are
- Mark/BRL spend time to improve it;
- an external wiki maintended by someone (already tried and failed)
- the current Bmax online documentation (the 'manual' section)

A possibile mix of the above could be a program that 'reads' from the on-line help (mainly the user comments & code snippets) and changes/integrate the local documentation. Or just a link (already suggested) into the local help to the 'remote' one.

This is the situation.

(of course this is only my personal opinion)


TaskMaster(Posted 2009) [#27]
Better documentation is a valid request. I don't see why the response has to be "You don't like it, don't use it". Any request to improvements of the language are fair to be asked for. No different than if someone asked for some other improvement.

Sure, there are other means of figuring it out, looking through the source, searching the web, asking on the forums, etc. But, I would think that better documentation could help sell more copies. Heck, they could probably even make a bit more money off of it, by offering a hard copy manual for a profit.


RmB303(Posted 2009) [#28]
I have to agree that there is a lack of support in the documentation for complete beginners.

Just listing the commands in the docs, and having numerous examples 'without' sufficient explanation for exactly what they are doing and how they work makes is hard for the first-time programmer, which I suppose BlitzMax is perfect for.

The manual which came with Blitz Basic on the Amiga was excellent, introducing the concept of conditional loops, variables, collision detection etc in a friendly and informative manner.

That is what taught me how to code - although I'm now having to learn again after a long break away.

Just got Maneesh Sethi's book, and that is helping a lot :-)


Mahan(Posted 2009) [#29]
This is completely untrue. The Express Editions may all be used for commercial use, ...



My mistake. You are absolutely right.