Will there be a manual?

BlitzMax Forums/BlitzMax Programming/Will there be a manual?

poet(Posted 2005) [#1]
Now it“s nearly one year that the first beta versions of Blitzmax were available. Still I am missing tutorials of a "normal" quality.
All I have tried up to now failed... (too many mistakes, so no tut would have been better...)
Will there be light or does this go the same way I already know f.e. from Linux, where you have to find out things yourself?
After all the other products have tutorials I awaited one for Blitzmax too....
Mipooh


Who was John Galt?(Posted 2005) [#2]
There will be an update of the docs at some stage. Best way to learn is from demo code and asking questions here.


ImaginaryHuman(Posted 2005) [#3]
Or experimenting yourself.


Russell(Posted 2005) [#4]
But yes, your general gist is correct: BlitzMax needs some serious attention to documentation, as the included one is not really acceptable.

And yes, too, one year is too long to wait for a real update to the docs.

(Yes, I know Mark is busy, but there isn't a single person at BRL that can do this? This is not a trivial unnecessary 'extra' that would be 'nice' to have: It is pretty much required in a professional software package to be taken seriously. One person, devoted to docs only, could write a really good one in less than a week...)

Russell


Amon(Posted 2005) [#5]
One person, devoted to docs only, could write a really good one in less than a week...)



True, also if the coomunity chipped in it could be done in a few days. All it would take would be for those fully capable with BlitzMax already to go through the command list and write out an example each. If everybody did this BRL wouldn't have to and everybody would get the Docs they want.


Will(Posted 2005) [#6]
I think the issue is - blitzmax is not a good first programming language to teach yourself. That doesn't mean its not a great language to know, and the first one to want to learn - but it doesn't have much out there for teaching yourself. I think we maybe should chip in and make a wikibook that takes you from fundamentals to the production of a game, for someone with no prog. exp?


slenkar(Posted 2005) [#7]
we already have the WIKI, isnt that as good as a manual yet?


Dreamora(Posted 2005) [#8]
Its a quite bad manuel if you have no internet at your de machine
A manual needs to be usable from the IDE itself not using other external things ... wiki are only usefull as fall back if everything else breaks


acr01(Posted 2005) [#9]
Some smaller wikis have a feature that lets you download the entire wiki as an archive package for offline reading (see http://senseis.xmp.net/?SLSnapshot for an example). Maybe if blitzwiki had this feature and the downloadable version could be integrated into the IDE, it would be a start in filling the role of documentation. Of course, ideally Blitz Research would provide the initial draft of content, but even if that doesn't happen, this might still be a good option.


deps(Posted 2005) [#10]
Maybe if blitzwiki had this feature and the downloadable version could be integrated into the IDE

I added a link to BlitzWiki in BlitzMax/doc/index.html
Not the same thing as you wanted, but close enough. :)


Will(Posted 2005) [#11]
I think the blitzmax inbuilt command reference was pretty good - every piece of code was one click away from an example application.


Matt McFarland(Posted 2005) [#12]
Will you've got to be kidding me. Thats completely untrue. Most of the commands in the index dont show good syntax examples at all.. 'Matter of fact it looks like their examples are fit only for someone who knows bmax to begin with.. Period!

There were only a small amount of functions that were explained. Where as MOST of the functions, commands are just showed in a raw form that looks alien to their actual usage. For instance you dont have to put :Tblah at the end of everything, sounds are not Tsounds, and the stuff they put in the arguments (in the parenthesis) are not explained at all. Not even are they told that they are required or not. and I paid $80.00 for this? BUT ITS OK its worth the $80.00 - only because I'm connected to the internet to download the latest tutorials and ask questions from a wonderful community. But if there was no internet or no community I would not have gotten past "hello world" for weeks and would have simply given up.

Honestly I've only used the manual like 2% of the time while learning bmax. The real reason why I have learned enough and continue to learn bmax at a pleasing rate is because I've used OOP prior, because of Wave's tutorials, Warpy's helpful enlightenment, and because of the community.


FlameDuck(Posted 2005) [#13]
One person, devoted to docs only, could write a really good one in less than a week...)
I think you're vastly underestimating the work that goes into writing documentation for anything as complex as BlitzMAX, never mind actually writting good documentation.

Most people I've talked to seem to agree that Wave, BlitzMAX tutorial pretty much covers what needs to be covered.

Maybe instead of just criticizing you could offer up some constructive problems you're having specificly, or come up with suggestions as to how one could improve on the documentation.

Most of the commands in the index dont show good syntax examples at all..
Examples, examples, examples. They can't fix it if they don't know what's broken, and "You've got to be kidding me" is not helping. I too find the examples and the command reference incredibly helpful in most cases. Then again, I'm used to MSDN, so that goes without saying.

For instance you dont have to put :Tblah at the end of everything,
No. But you should. You don't have to indent your code either, or write it on seperate lines.

sounds are not Tsounds,
Yes they are.

Not even are they told that they are required or not.
Yes they are. All parameters that don't have default values are required. A default value is identified by a preceeding "=" sign in the parameter list, followed by the value in question.


Matt McFarland(Posted 2005) [#14]
Mikkel,

TSounds are Sounds (actually) but that was not clear to me at all in the documentation, further resting my case. Again, let me express that the documentation only works for experienced programmers! (like you)

They do not explain the arguments, they do not explain the concept behind the T and the colon and what its all about! They do not explain which arguments can be left null or how the commands are used. They just throw it out there and make a demo that doesnt reflect the raw format in the documentation which makes things FURTHER confusing.

Especially when I looked at the example that just said Playsound (sound,false) and when comparing that to the syntax they put in the manual which reads something like TSound = Playsound (sound:Tsound,false) --- OR SOMETHING like that.. Either way, the exact letter-for-letter with the exception of the variable / args syntax in the manual compared to its real usage in a BLitzMax program are hardly the same.

Here's a short, and simple statement that backs my earlier one and further implies that You've GOT to be kidding me! : Please further explain the arguments, and please use a full example of how the commands would be used in a program!!!

Maybe the one-liners with raw syntax formats WORKED for you but I assure you they will not work for the majority. It's not really fair to imply that the docs are perfectly fine because they "dont need fixed" when only a minority can comprehend them.

Furthermore, I have solely learned how to make a spline editor and my own shmup in process by hanging out in the beginner's area and talking with the experts that help everyone out. Wave's tutorials actually got me to understand the basics of bmax very well. I think Wave's beginner's guide should be put straight into the documentation.


Amon(Posted 2005) [#15]
I'm with Matty McFarlandy on this. The docs no matter what people say are not newbie friendly.

I don't know if this is considered a Troll Post. :/


Matt McFarland(Posted 2005) [#16]
Honestly what would be great for BlitzMax (especially in the demo version) is to have an opening window when the user firsts turns on the IDE that says "Welcome to BlitzMax!!" and let it show the user Wave's tutorial.. or atleast put a link to his tutorial in the Welcome-dialogue-box (and make the URL of this link be part of the package folks!) and that would probably increase Bmax sales by atleast 10% if not more.

Otherwise people can download this BMAx demo and think to themselves "no tutorial?" and think "I'll have to get on the forums" and then think "but wait maybe there's a better supported program?" and end up skipping the beauty of BMax because of its tutorial-free, short-hand documentation first-impression.

It can take a lot more courage, or even resources (not everyone has the net) for a person to hop on the forums and ask for help or search for tutorials and ultimatley kill the program's appeal.

Again a quick fix for this problem (seriously think about this) would be to add Wave's Beginner's Guide right into the blitzmax manual (and make the person be aware of it's existance when they first run the program too)

Of course, only if Wave was willing to let it be a part of BRL's official applet.


Oddball(Posted 2005) [#17]
Examples, examples, examples
Ok FlameDuck I have provided below a list of commands that are currently under explained for newbies or are lacking adequate examples. With each command I have also provided the link to the command in the docs. The list does not include type methods as non of these are explained at all.
Hope you find it useful Flame. :)


tonyg(Posted 2005) [#18]
I had a lot of trouble with the doc coming from bb.
It assumed a lot. Now, it all seems reasonable but it's been a long process.
I looked at some of the commands again and thought 'why didn't I understand that before'. The answer is familiarity with the product rather than helpfulness of the doc.
I believe even BRL has acknowledged the doc 'could do better'.


xlsior(Posted 2005) [#19]
Maybe instead of just criticizing you could offer up some constructive problems you're having specificly, or come up with suggestions as to how one could improve on the documentation.


I think the main problem I have with the docs is that they are pretty decent, provided you already know what you're looking for -- which is a poor assumption in most cases.

Something as basic as the difference between a pixmaps and images for example, could really use more elaboration... Let alone that 'pixmap' isn't exactly the kind of term you'd be searching for out of the blue when you first open the help. A basic chapter on how graphics work in Blitzmax would be very helpful to new users: DirectX vs. OpenGL, images vs. pixmaps, the various types of flip, refreshrates, information on optimal image/texture sizes, etc.
Those are the kind of things that can make or break a beginner project.

The forums are a great resource when learning the language, but it would take a *lot* longer to pick up the language if all you have to go by are the docs...


FlameDuck(Posted 2005) [#20]
Hope you find it useful Flame. :)
I do. Thanks.

it would take a *lot* longer to pick up the language if all you have to go by are the docs...
Well I think we can all agree it's a good thing that isn't the case then?


xlsior(Posted 2005) [#21]
Well I think we can all agree it's a good thing that isn't the case then?


It isn't the case for us on the forums here right now, but there are plenty of people that can't have internet access 24/7, where the docs are pretty much all they have at their disposal.

I know I've hit my head against the wall a few times when my DSL line had some intermittent outages and I couldn't go online to look up things. :-?

Forums, wiki's, etc. are a great supplement to a manual, but I really don't think they should replace it.


Dreamora(Posted 2005) [#22]
The procedural docs are nice but the OO is a beast of darkest hell.

Even now, where BBDOC was extended to at least show up the methods etc its still not far better than before when you had to crawl through the sources (which is what I did with the first buyable version already).

Best help to it is TheShadows HotDocs which does what BBDOC should have done ... But still, the whole things looks more like the B3D kiddie procedural thing instead of a "more professional" procedural + OO thing.


Dreamora(Posted 2005) [#23]
The procedural docs are nice but the OO is a beast of darkest hell.

Even now, where BBDOC was extended to at least show up the methods etc its still not far better than before when you had to crawl through the sources (which is what I did with the first buyable version already).

Best help to it is TheShadows HotDocs which does what BBDOC should have done ...

But even then its not the best as the bbdoc stuff in the modules was mainly focused to procedural, although I thought procedural was just put in as a "plus" while OO should be the main, not vice versa (there is still much in BM you can't use in OO style like images etc)


chriscrawford100(Posted 2005) [#24]
Hey guys, I was wondering - does anybody know of a good, solid, cross-platform file format that supports the features of a standard Windows XP help file? The only thing I know of offhand is PDF (which is close but probably not ideal). I was really shocked at the state of the docs - not beginner-friendly at all. Had I not already had programming experience (and if it weren't for this fantastic user community) I wouldn't have made it very far. There should at least be an easy way to search all the docs at once. So I was thinking that converting the docs from lots of seperate HTML files into something unified would be a good first step towards making them more useful. Barring that, does anyone know of a utility that will allow searching lots of HTML files at once? I guess I could copy/paste them all together... ;)


Mark Tiffany(Posted 2005) [#25]
I keep thinking that it should be firly easy to write a simple file search piece of code in bmx, that we can (now) slot into the MaxIDE...but never quite round to trying it...


N(Posted 2005) [#26]
1. Bumpo.

2. Maybe BRL should consider buying out that HotDocs program.


GA(Posted 2005) [#27]
Ok, I might get linched for saying this, but the one great thing about the original dark basic was having a printed manual by my side.

I know it is a long shot, but could a printed manual ever be avalible?


Augen(Posted 2005) [#28]
I also think the docs are not beginner friendly.

I agree that a printed manual would be great. The only problems with printed manual would be 1. would BRL even consider that?, 2. the manual should be updated online to reflect changes to the language (would BRL even consider that?), 3. how much would a printed manual cost? (to make, print, sell?), 4. why doesn't Wave compile all his tutorials together, add a detailed and explained command reference, and try to get a publisher, so he can sell as a "printed manual"? :) He could do updates on his site if the language changes.

There were 2 books that I know of on 2-D programming using Blitz and/or Blitz3D. I don't know the sales figures, but I bought both. Has anyone considered doing a BlitzMax book?

Edit: Good points and suggestions NoodleCower (see next post).


N(Posted 2005) [#29]
Printed manuals are too expensive to consider for BlitzMax as far as I'm concerned.

Also, printing a manual and then having modules or the language change (because BlitzMax is still being worked on) is not going to bode well for people who buy said manual. Your best bet is to just print it yourself and throw it in a binder -- definitely cheaper on both ends.


Barliesque(Posted 2005) [#30]
A manual in PDF format would be ideal: It's searchable with Acrobat, and it's printable for anybody who wants it on paper. And with it being optional, the cost of BlitzMAX would be unaffected.

Maybe HotDocs could be used to provide a nice HTML help system, as well as a PDF output...?


DarrenS(Posted 2005) [#31]
If people are trying to say that having a manual that actually shows you how to program in the damn thing is a bad idea, then they ae crazy! I can't use this programming language because i am not a techhead, I want a decent manual that does what it is supposed to do, teach newbies like me how to program. How the hell am I supposed to figure this stuf out if all the techstuf means nothing to me in the first place eh?
Get your act together blitz research and get a decent pdf manual out for people to download, christ! I find it funny that Blitz has always had a reputation for crappy documentation, even blitz for the amiga had awful docs, it was up to the magazines to give people the tutorials we wanted.


tonyg(Posted 2005) [#32]
Not sure what's happening with this...
BlitzMax for the Absolute Beginner


GA(Posted 2005) [#33]
I am not the worlds biggest expert in publishing matters but cafepress do offer an on demand publishing service should a printable manual ever be produced:

http://www.cafepress.com/cp/info/sell/books.aspx

The dark basic manual I have somewhere was just a Wire-O of about 150 pages, it did go out of date with updates but it was nice to have the core language in my hands so to speak.

If Blitz Research were ever to produce a full and complete set of docs, it could be considered an extra insentive to do so, to sell the hard copy via such a system...


Jeroen(Posted 2005) [#34]
Cafepress=BAD! Very BAD!
Awful quality and service.


GA(Posted 2005) [#35]
Any better ideas? Anybody know of any other on demand publishers?

If it is true that docs have been a problem since amiga days, then comunity brandishing a few sticks simply doesn't work. They already have bought the product, what is the insentive?

Lets try laying out a few carrots and see if we can lure BR into making documents with the offer of a few sales of a hard copy of the docs once produced? I mean, they are already half way through the job, if they finish it they might make a little money from an avanue they were not expecting to make any money from.

*me starts waving around a few carrots*


DREAM(Posted 2007) [#36]
it would be nice to have an example of each command as B3D does, i am managing to bumble my way through it, but the extra help would be nice.........


Matty(Posted 2007) [#37]
I don't own a copy of blitzmax - but - after reading this thread, without realising it was a year old, am wondering has anything changed with the docs? I do recall downloading the demo on my other PC about 6-9 months ago and felt they were a little sparse.


Blueapples(Posted 2007) [#38]
Personally, I find the documentation to be adequate. Not knowing your experience level however I can't really say if you will too. I would recommend not evaluating a language on it's documentation alone, but rather in it's range of features, depth (availability of library source code for instance), community, and yes--documentation. Those together are more important than any one thing.

The community around Blitz products in general is really good, always willing to lend a bit of code or answer a question. The language itself is a joy. Overall, a big plus.

That said I do think the documentation needs some help. What I would like to see, and hopefully Mark can comment on the possibility of this happening, but I think simply adding a BlitzMax manual to the site at http://blitzmax.com/Manuals/_index_.php would be very helpful. Then when we find an example lacking we will comment on it, provide a new example, etc.

Perhaps once a month someone can go through and integrate those suggestions into a coherent revision of the manual so that in a few cycles we will have greatly improved documentation.


theHand(Posted 2009) [#39]
Ande Blueapples' word was done, ande many rejoysed as thay beeheld the manule, online fore all to se.
Ande manne męd comments, naye, additshons to the manule, purforming tests ande...

Wow, that's hard.
Anyway, I do wish they would make a new pdf of the online versions (with the user comments appended appropriately) every 6 months, and post it over the previous one.
If not, then I'm going to start doing just that. Getting all the html together and formatted properly though is a pain.


skidracer(Posted 2009) [#40]
I have been considering this vexing problem also.

The last job I had at BRL was a manual, we used LuLu and as you can see Mark priced it very generously.

It would be a good excuse to give all the docs a spring clean if such a volume was produced for BlitzMax.


Brucey(Posted 2009) [#41]
Where do I pre-order? :-)


degac(Posted 2009) [#42]
Some questions-requests:

1) Blitzmax's manual in the official manual section seems to report only the commands generated by the .mod source.
I just noticed there are NEW commands as MouseXSpeed - MouseYSpeed..., but the online section dont' show them (at this time: 05 september 2009) - maybe because bmx 1.34 is still in RC form - but I would like to know if *someone* need to 'update' manually the online section.

2) It will be a great addition to the online manual to find the 'Language' section (as called in the HTML local/IDE help) with the possibility to add comments: every month there is someone asking about (for example) array and how to resize/delete them (recently I need to re-search in the forum how to resize an array-of-array (array[][]) - and the local html didn't help...

The idea of BlueApple is still good:

Then when we find an example lacking we will comment on it, provide a new example, etc.


Probably someone (Skid or Mark) should emphasize more this aspect so people will be aware of it and will start to use it/contribuite to it.
I found sometimes that a solution to a problem (like the array one) is given by the community - but it remains in the forum - and it's like it's lost...

As consequence - when/if the online manual is 'filled' with comments and examples, then a 'real' manual can have reason to exist - even only as PDF file.

PS: just my point of view of course.
PPS: I know there are/were people proposing the idea of a wiki - but the results is a lost of time and resources. I think its better *focusing* efforts only in one way.


beanage(Posted 2009) [#43]
Is there actually a complete bmax specification?