Blitz MAX Documentation Proposal

BlitzMax

Seeing as this topic has raised its head again fairly recently in another post I thought it might be time to make another appeal to Mark regarding BlitzMAX’s documentation. I have come up with an idea that I think may be the best compromise. I notice that there are some examples in the current documentation so it seems it wouldn’t be a major task to include these into future documentation releases if there were examples readily available to be put into the documentation. What I propose is somewhere where the Blitz community can post or email their examples to so that Mark can easily include them into the documentation without too much time and effort. He could then release updates once in a while. I think this would be the best solution all round as it means little extra work for Mark and allows the community itself to have a hand in improving something that is seen to be important to a huge number of MAX users.

I know there is the Blitz Wiki available but this is hardly as easy and quick as being able to press F1 and have the command and example right there like in Blitz 3D, it also requires an internet connection permanently available and I for one share my internet connect with my brother and I’m sure I’m not alone in not having 24 hour internet connectivity so really without integrated documentation Blitz MAX is taking a step backwards not forwards.

What do other people think to this idea?

> What do other people think to this idea?

I couldn't care less. :)

Sure the instuction manual has seen better days, but those that want to, will find out things for themselves and work around it.

And if the manual does get a kick start, that will make people say 'why not work on the 3D engine instead of the manual!'. Then we'll have people saying why not fix the bugs instead of adding new features. And then we'll just kickstart the same old tedious arguments and moaning that we always get.

I mean all was asked was does anyone have any 3D tutorials for Blitz3D ffs. :)

i hear ya

I've suggested the above before and had no response.

Writing good quality, self-contained examples shouldn't be that hard to do (although it would need someone to quality check them), and from what I recall can be incorporated into the current help very easily - you pretty much just drop the example code in the correct directory. There are so many commands that just don't have examples, and most could very quickly be added.

I'd be happy to take on any co-ordination / QC role of such an effort, then BRL wouldn't have to do anything. But I won't do anything until I knew that any effort would actually make it into the full docs...

I think that BRL, should hold some sort of competition (Call it a job interview if you must), to find the best writer/explainer and the WINNER, gets a contract to write the BMax docs.

What would happen, is that Skid posts ten, (For example), problems on a Monday morning. And whoever produces the Best* answers by Friday night. Get a contract to write the manual

*Best to be Predefined before the competition, but not here

well... all i've got to say on this is...

1- why not work on the 3D engine instead of the manual!.

2- why not fix the bugs instead of adding new features


ahhhhh... this'll probably just kickstart the same old tedious arguments and moaning that we always get.

:)

--Mike

I wouldn't mind exploring undocumented commands and boldly create examples where no one has boldly created examples before..

In any case: examples should be as small as possible and must run in superstrict mode.

@Red, a question

When you have finished your "UnderwaterNotsinking" device simulation.
If DX11 came out the next day would you still call it finished?

How about every BlitzMax user submits one example for a command that doesn't have an example?

hahahahahahahaaaaaaaa... c'mon, i can't take any more of this... i'm laffing so hard, i'm starting to cry...

it's wayyy tooooo early in the morning for this...

"UnderwaterNotsinking" device simulation.... hahahahahahahahaaaaaa...


--Mike

otoh, does every command need an example?

observe:

Function CheckMenu( menu:TGadget )
Description Set a menu's checked state.

Does this need an example?

What kind of a prize is THAT? :O

yes, i think it does CS... maybe not for most of us here, but maybe for the BMax Newbie who has just joined the crew, and is still a lil unsure of stuff, and needs a bit of handholding...

the return type... what is the return type... does it return anything... lil things like that...

to me, the function is structured as more of an interrogatory function, that checks a menu for something or the other...

so maybe a lil handholding might be appropriate here... and afterall, that's partly what the docs are for... right... wrong...


--Mike

Another option is to have not an example per command, but (in case of e.g. CreateMenu) to have one bigger example (yet as small as possible) featuring all the CreatMenu-related commands.

worked in the BlitzPlus and Blitz3D docs...

Yep.

Yes every command should be documented, that DrawImage command still gives me a load of problems even to this day.

I don't need new BlitzMax docs. It's kinda like the Da Vinchi code figuring them out, but I've cracked it a while ago...using BPlus helped a certain amount, but uh not a lot.

But Grey Why does there need to be so many books Explaining the "Da Vinchi code"

Not necessarily. In many ways, the fully OO stuff confuses people, and actually could be considered as obfuscating an example. I think you should have a good mix of both : in fact, maybe a version of each for each example?

Most do, but no, not all of them make sense. Many examples can also be shared across several commands.

Exactly - it really wouldn't take long to make an impact, even if only 10 people created 10 examples a month...

.... which, if they're not put into the official docs or a community doc, would be 'lost like tears in the rain'.

from Blade Runner... right?

--Mike

'lost like tears in the rain'

"time.... to die!"

^_^

Mark Tiffany: When I'm talking about short examples, I was aiming at the prevention of examples that add a whole lot more than just the explanation of the command. it's all these extras which look obfuscated to the user, it steals away the focus. Not in the least because in some cases all these extras are somehow related to the command in order to work, which means that the user has to read the whole app in order to get the idea of the single command.
In quite some cases all these extras are written in a non-consistent style also which again scares away beginners. The B+ manual, tho good, has quite a lot of coding styles, quite a lot of them are actually to be called 'ugly' or 'quickly hacked'.
Also, a lot of examples assume 2d-related code and based on polling. Event-based code is to be found with a mere candle. While I understand that Blitz' classic focus was on games (usually 2d/3d and polling), the inclusion of a GUI module should hint at all-round usage so it should also include event-based examples for 2d/3d/game cases.

Why don't we just, uhhh, use the wiki? When you press F1 it takes you to the appropiate BlitzWiki article.

Then everyone can improve the manual, add good examples, etc.

Not smart when you're with your notebook in a train! Manual needs to be local. Apart from that, we want the helppage in a splitsecond, not 10 seconds because you need to connect to the wiki page, browser needs to wake-up from cryo etc.

He he, both quotes above by same man in the very same thread !!
You go figure it out by yourself Enay, I'd like to see all commands properly documented ;oP

Seriously, your first quote is ridiculous, this is a product
they sell for money, giving the buyers the necessary means
to use it properly is vital for sales, customer satisfaction,
future life of BMax and the amount of marked-percentage.

I'we said it before and I'll gladly say it again, Mark and
his crew are (next to geniuses) programwise, but when it
comes to public relations and customer care, they know less
than nothing !

I wouldnt mind if there was a "Real" book, that I could hold. Even A pdf I could print, (I know I could print the docs we have now, but would you?)

I wish the community could make documentation, and then it gets included into the official download. That last bit is very important




please.
I've never used maxGUI, so I don't know what this does. And looking at the docs is the first thing I would do. I would think this:
I thought a menu was one of those File - Edit things.
How can you set something's state without passing a value to set it to?
Does the function return a value?
Ah screw it

> You go figure it out by yourself Enay,
> I'd like to see all commands properly documented ;oP

But that lead nicely into my DrawImage joke.

Personally I rarely use the documentation, better to play with and figure it out yourself (then you learn something that sticks with you)
Failing that, ask on here :)

With commands added regulary.. it wouldn't be smart.. :P


Function SetState()
state=1
End Function

Function UnsetState()
state=0
End Function

Function ToggleState()
state=1-state
End Function


Then it would've something like :<type> after the functionname and before the (arguements), that's generic BMax terminology, not GUI-only.

Ohwell... screw it too.. :P Every command an example or a reference to one generic big example featuring all related commands.

Why not? The manual could be ring bound, then every month A PDF with the changes could be published.

I would sure love to see more examples.

> With commands added regulary.. it wouldn't be smart.. :P

Real books SUCK BEYOND BELIEF! They're outdated the moment they're printed and you can't perform the awesome time saving commands like on a PC such as "Search" and "Copy & Paste" into your code.
Why anyone would want a book in this day and age for a programming language is beyond me.

a lot of things appear to be beyond you E... real printed matter has it's place...

... but maybe an EBook, or .CHM, or something to supplement the printed matter...

... just for the ENAYS of the new meillenium :)

--Mike

Your triple fullstops are beyond me.

yeah... i know E...and those are only small dots...

imagine if you had to deal with more complex concepts... walking, breathing, washing your hands.


what say we try to let this topic stay focused, and dispense with the pathetic attempts at humor... ehhhh

it *IS* sorta important...


--Mike

Becauese people are idiots.

Bollocks. Name one mainstream product that ships with good (or any) documentation. Let me just pre-empt anyone claiming MSDN is "Good Documentation". Look up Serialization Exception. I'll wait.

Back again? Okay, tell me how "An exception was thrown during object serialzation" is going to help me figure out what's wrong.

Little to no documentation is simply a fact of life for propgrammers. You want to be in the technology game, you'll just have to accept it and move on.

They tried that with BlitzBasic 2.1 for the Amiga. Not only did it spectacularly not work, but after 6 months your manual was reduced to a handful of loose leaflets.

If people spent half as much time programming, as they did complaining they wouldn't need a manual by now.

> If people spent half as much time programming, as
> they did complaining they wouldn't need a manual by now.

Talk to that wall behind you, you'll probably have better luck ;)

Well, the help system in BlitzMax is terrible, especially Linux... That is just beyond useless!

I know BRL wanted to freshen up the docs, but my personal thought is 'if it ain't broke, don't fix it'.



Erm, Blitz2D, Blitz3D and BlitzPlus! There's three straight away ;)

Decent local documentation IS relevant Flame, I wonder how many threads in the BMax forums could have been answered just by including a simple example in the docs, with relevant infomation e.g Supported music/sound formats.



Eh? I'd agree with you if we were talking about free IDE's like Visual Studio Express packages, or Dev-CPP, but people have PAID for a product, and in payment, expect to receive a level of service that constitutes the payment!

In any product, especially technology, after sales support is a must, doesnt every agree that Antony and his Aurora after sales support was a sham?

My Linux docs are a sham, I demand them to be fixed, why? Because I paid for them, and they are unusable! That's not complaining, that's stating a fact!



Your right, but, they'd still spend more time online asking questions, searching for answers to the smallest of things, so your really in a no-win situation.

Dabz

I think that's mostly just the HTMLView thingy.

Nice try. Too bad neither are really mainstream products, or had decent documentation when they where released.

Anyway, what's so good about the Blitz3D documentation? I don't remember it being significantly better than what BlitzMAX has now.

That's right. People did pay for a product. A product which they got. They paid nothing for service - they get all that for free (basicly forum and updates), and by free i mean "on BRL".

Not really. It depends on your market segment. If you where selling to acedemic circles, then yes, you would need textbooks and reference manuals. If you're selling to other developers, less so - most will be able to figure it out on their own. If there is anything BRL can be criticized for, it's not being upfront about who their market segment is, aside from wierd and wonderful people (which explains so much about the forums).

You assume too much. I'd take people posting genuine BlitzMAX related questions on topics they don't understand, over this pointless whineing (no offense) any day.

My assumptions are based purely on personal experience! :)



Well, the Blitz language is supposed to be 'powering the games that millions are playing', if Blitz IS powering games millions are playing, I'd say that was pretty mainstream! ;)



It was significantly better, in a sense it was easy to navigate through, it was comfy on the eye balls during a long programming session, it just worked. Currently, it seems that David Blunkett's dog made them! :)



No offense taking, but a decent local help system (in my eyes) is much better than forum visits! Anyway, A discussion is good for the heart and the soul, plus, it stops me glossing the skirting boards! :/ Which I'll probably get my arse kicked from 'er indoors if I dont get them done!



If it's got anything to do with BRL, we'll probably never know, lol! :D

Dabz