Great work on user-made docs!

I just wanted to put a big "Thanks!" to everyone who has at least tried to do something in the way of Bmax docs.

But now it's time for me to vent a little bit on the sad state of BMax's official docs: (Sorry, BRL, you have an EXCELLENT product here, worthy of much respect, but your documentation stinks. ;) )

I find it increasingly frustrating every time I'm looking for how to do something in BMax and either I can't locate it (no search? Come on, BRL!), it's description is extremely lacking or no examples are given whatsoever.

Now, I hate to complain and not offer a solution, so here it is: Is there someone here who considers themselves an 'advanced' user (who is also perhaps somewhat familiar with writing clear/concise/thorough documents) that would be willing to write a totally KICKASS official documentation?

If so:
1] How much would you charge to do it?
2] How long would it take?
3] Would BRL be willing to pay an outside person to do it?

Ideally, it would integrate with the BM IDE in the same way as the current one does. Also, it would hopefully include an actual User's Guide that really explains the 'Hows' and 'Whys' of Bmax, not just 'Here's the command and its parameters'.

Ok, so does anyone have the time?

If I were more proficient in the language I absolutely would do it myself, and probably for free :)

Anyway, that's my $.02

Russell

"They [Enthusiasts] are the ones who first appreciate the architechture of your product and why it therefore has a competitive advantage over the current crop of products established in the marketplace. They are the ones who will spend hours trying to get products to work that, in all conscience, never should have been shipped in the first place. They will forgive ghastly documentation, horrendously slow performance, ludicrous omissions in functionality, and bizzarely obtruse methods of invoking some needed function - all in the name of moving technology forward. They make great critics because they truely care." - Geoffrey A. Moore

The question is, if you're not an early adopter, why have you bought BlitzMAX before it was fully matured?

Probably not. Enthusiasts aren't the best at making documentation. That's better left for pragmatists.

To answer your questions more directly:
1] Prentice Hall usualy charge between 100 USD and 200 USD for such books.
2] About 6 months.
3] Probably not.

Sorry to disappoint you. However:In which case I offer my services as a consultant. If you have any questions at all, feel free to contact me. If that's not good enough, I'm sure that (if you're serious about this) and make a concise proposal to BRL, they will at least consider it.

The strongest arguement in favour of your case, that I can think of ATM, would be that an improved documentation is absolutely vital for BlitzMAX to appeal to pragmatist buyers, and have any chance at all of mainstream market penetration.

You wasting your time. The guys that should be commenting about the lousy documentation is BRL and sadly they NEVER comment about anything. Do they even visit the forums??????

Since they post here regularly, I'd have to go with, yes.

The documentation for Blitzmax really is awful, though. The general haphazardness of it all, coupled with the lacking search feature and the fact that the IDE doesn't even have an autolist facility, makes searching for and using functions/methods something of an ordeal.

It strikes me that the only people BRL want to sell Blitzmax to, are the people who have already torn their hair out because of experiencing similar problems with other BRL product in the past. Anybody new to BRL products, or even new to programming in general, is simply going to give up after a few weeks.

The documentation is as important as the product itself - or at least it should be.

a) Yes.
b) They do comment on stuff. Maybe not regularly or immediately, but they do.
c) We all know the documentation sucks. I gave up stating the obvious and I would advise you to do the same in the interest of keeping your sanity. If they want to sell a product with bad documentation then they can do that.

They lose most in the end since BRL seems to have pretty much relied on word of mouth aside from the occasional send-out to some website, and when we're all saying the documentation sucks to potential customers it's not going to do them a whole load of good. So if you're going to say this to anyone, I'd suggest telling it to other communities. Provide an evaluation of the product (and obviously be fair, don't just say it's crap since it really isn't [in my opinion]).

If you really want to get the point across, make their sales go down because of the documentation. Deprivation of would-be profits is a great tool.

That's a good idea.

Let's destroy BRL's profits so that they don't get new sales and cannot afford to continue development of Blitzmax. That way BRL don't get any more money and we don't get any more updates to a language which badly needs updates in several areas.

Masterplan, Noel.

As I see it...
1) BRL could (and should) make the doc better. Failing that...
2) BRL (or somebody) could come up with a nice little program where Users can enter updates to the documentation which are not overwritten on docmods. Even better online facility for people to enter improvements and code to the doc which we can download and include in the Bmax doc.
3) BRL run a weekly compo for best documentation for chosen modules with BRL product discount voucher to the winner and inclusion into the official doc.
or
4) The community come up with a way of doing it... somehow.
Could something like Hotdocs have an add-on to create and include user-written doc?

:) Well i haven't done any improvement but i translated the language's doc into french to make it easier for the fr community people who might not be so keen on with reading it in english.
When it was time to do the module's doc part i left it for i felt discouraged because there is not much description of the various commands for each modules. If the Doc would be better (sure it will in the future) that would be really a great thing for less experienced coders (like me) who are having a hard time learning Bmax through the oficial docs.

Hopefully there are the forums which are always a very good place to share,learn and gather information we are looking for :)

www.blitzwiki.org ? Might be a good starting place for creating more detailed docs...

Alex.O, Yep, that looks great but is really out of date (e.g. no hooks, events, maxGUI etc.
How do I access it via F1F1?

You don't really need a search if you put your cursor on a token and press F1 twice, but I suppose that entails knowing what the command is that you need ahead of time. Would be nice to be able to search for any given keyword.

If sales dive then they take a hint and work on improving the documentation and if that's the reason behind not purchasing it.

Given that it's pretty much the only good product they have besides Blitz3D, they chances of them just abandoning it is very, very low.

blitzwiki... hm i think it is too hard doing this per hand. here are too many changes in blitzmax. and if here come new update - you must rewrite many docs...

so that i decided to create new program - called hotdocs... this program create new - much better docs...

There are two significant scenarios that could play out here.
1) BlitzMAX sales take a dive, so they start focusing on Blitz3D documentation instead - as that's the program that is in larger demand, it makes sense that that's the program they divert more of their working hours to. If you want texture compression in Blitz3D, I think this is a viable solution.
2) BlitzMAX sales take a dive. BRL are forced to take part or full time jobs to maintain a steady income stream. Say goodbye to any updates for anything for a long, long time.

I still don't understand why someone who expects a mature product would buy it within the first few months of release.

Who said they expected a mature product within the first few months of release? Heck, I bought it when it was still in beta and knew what that entailed. I bought it within the first few months 'cause I expected BRL would eventually make the language as good as it is now, and they did.

Ok, good replies, everyone.

Now, couple of ideas:

- If the BlitzWiki (or an alternative BlitzWiki) had the same hierarchical layout (and initial content) as the included docs then we could improve it from what it is without starting from scratch. This may still be necessary, however...

- Whatever we do as a community has to be downloadable as one entity. Maybe SyncMods could even offer to look for this when we update?

- I am going to pore over the tutorials for BMax (some really good ones in there) to bring up my 'expertise' level so that perhaps I can contribute something worthwhile. I have written a User's Guide, but it is unfinished. Perhaps I will be able to finish it after this... (I like to be able to 'wrap my brain completely around something' before I try to convey it to someone else: The whys and hows make the logic so much easier to grasp to a new user).

- This documentation, whatever form it eventually takes, MUST (IMHO) assume NO prior Blitz knowledge, at least in the User Guide. The current docs make huge assumptions about what I may or may not already know...

- EXAMPLE, EXAMPLES, EXAMPLES!!!!!

Anyway, I will do what I've said here, but it may take some time as I have a full time job and a newborn (born 3-17-2006) on my hands ATM :)

Later,
Russell

The docs aren't great, but BMax isn't really aimed for newbies. OOP is over the head of people who have never programmed before. It seems to me the audience is existing Blitz users or people using competing products to BRL's, ie, people with programming experience. Somebody did a kickass beginners guide to BMax in PDF format that should more than help anybody get over any hurdles in migrating to BMax from another language.

I'm gonna teach my son OOP from the start so he'll find arrays and function based programmng weird. To think he may never type 10 print "I'm Cool" 20 goto 10... :-(

someone should write a book like filax(?) did with blitz2D... It could be done in PDF format and sold as an e-book. In doing so, documentation could be built alongside it.

@Unknown, I think that's a bad assumption to make on BRL's part (if it's true), that they expect new users to already have some knowledge of Blitz's prior products and/or OOP because this would significantly reduce the potential size of their new user base.

OOP is strange at first, no doubt about, and it has uses (especially in very large community-type projects - "Blackbox" functions), but it certainly possible to create very professional, commercial programs without using a single OOP feature. And, contrary to popular belief, it can be clean, fast and easy to follow.

I'm glad OOP is there in BMax for those who want/need it, and more power to them.

I still believe that OOP, at least as far as BMax is concerned, should be taught in the User Guide thoroughly with lots of examples, because someone in that new user group may have an "Ah Ha!" moment and produce the next Halo or Super Mario World or even...gasp...a Dbase clone.

Russell

p.s. I'm on page 13 in my new hyperlinked User Guide :)

FlameDuck: You keep saying early adopter. I bought Max when it was in beta. It has been one and a half years. Max is awell past the early adopter stage. The docs are now what I expected in beta and haven't really changed. Having things divided into sections the way they do is horrid.

If the docs in BMAX 1.20 are no better than the demo docs then I have to chime in and say they are horrible. Now I don't want to get flamed here but, 7 years ago (yikes has it been that long) I was an early adopter of DarkBasic. The docs were awful and kinda looked a lot like Bmax's today.
I decided that the quickest way for me was to completely gut the online docs and fix typos and mistakes and reformat everything into something I could ring bind and have open in my lap when needed. Took me a week and I am still credited by Lee Bamber in the Darkbasic docs even though I stopped using DB years ago and I am not active in their community.

So, should I have had to do this? No. My point is, it took me a week to do. I was motivated and had the conviction to get it done. Didn't take much more than me wanting proper docs.

So, my next question is this. Why are the docs for BMAX so horrible? My guess would be that Mark and company, like most programmers, find the tedium of documentation the least desirable thing they could spend their time on. In which case, for the love of God, please commission someone to do it for BRL and be done with.

We would love good quality docs more than anything else. Yep, bugs still exist. But consider this, those bugs will still be there for you to fix when the docs are done. Potential customers won't be.

I fully believe that if BMAX had professional docs and dash of marketing it could quite easily become very maintsteam, used by schools and pro's alike. Why it has neither of these is a mystery to me. I think Mark has made stellar products but really missed realizing the full potential of his efforts.

My last supervisor had a very good mantra which I fully adhere to in my professional life. If it isn't documented, it isn't done and if it isn't done it doesn't go into production.

Wouldn't the it be nice to see newbies come here with "normal" questions and the oldtimers around here respond with "RTFM" rather than the usual "search forums moron"

Mostly just wishful thinking.

Allan

I know Mark knows this is a sore spot for us (poor docs), even though he has never, AFAIK, responded to comments about it one way or the other ("Yes, you're right. We're working on it now." Or "Too bad, I don't have the time. Learn C++ first and then you'll get it.")

Hopefully, after Max3D is out and fairly sussed of bugs, we'll get some relief....Or someone will do it on their own and blow us all away.

Russell

EDIT I thought some of you might be interested in this: http://www.starwars.com/episode-iv/release/video/news20060503.html
(Yes, at long last, George Lucas has come to his senses and is releasing the ORIGINAL ep 4-6 in its ORIGINAL form - No Jabba at Mos Eisley, Han Solo shoots Greedo first, etc)

Could not agree more :)


I may not be the perfect candidate but I'll answer the call.

I do not consider myself an advanced BlitzMax programmer, however if it is relative and compared to someone entirely new to game programming and BlitzMax, then very much so ;)

About writing clear and concise, I do not think I can judge that myself. The beginners guide I wrote was not for beginners to programming, it was for beginners to BlitzMax, which I know have caused some confusion. And it got much longer and much more advanced than what I initially intended it to be.

I would be willing to write a totally KICKASS official documentation. I see nothing wrong in doing that, if it would actually be Kickass (if I wrote it without anyone to review it) that is another question.

Why do BRL intentionally ignore the fact that the docs is not that good?
I think it is something like this…
After working on BlitzMax for a very long time it was finally released. At this point they had to write some basic documentation, some of it had already been written while coding. When finally "done" they realized they could work months on just adding examples and improving the documentation's layout and design. Docs is not the most fun part of application development, so it was never done. New features and bug fixes was what the time went to, and still does. And as long as BRL do not desperately need more $$$ they have no reason to make Blitzmax more appealing to more people (like beginners or improving the information about blitzmax at sales), there is still plenty of b3d users who do not have max, and many of them will likely get it once the 3D module it out. By then BRL could keep working on new ideas, and the need to improve the documentation will be last priority again.

They have done a few things to lessen the burden on the docs.
1. open source
2. A tutorial forum
3. A link to the wiki.
I think it is a bit sad that this is where it seems to end.

I can not know if there is any truth in my story above, I'm only assuming something like that is the case, or what do you think?

You can drive a car with your feet if you want to, that doesn't mean it's a good idea. Sure OOP isn't a silver bulet, but that shouldn't mean we should dismiss it. Abstaction is a tool to handle complexity, thus a more abstract language will allow you to create more complex things in less time. It's not a matter of what you can do, it's a matter of how much time it saves (productivity you gain), not only during development, but in maintenance aswell.

No it isn't. Being an early adopter is not about how long ago you bought the product. Being an early adopter is about having a whole product and mainstream market leadership. BRL have neither, thus their current customers are early adopters as defined by the technology adaption life-cycle.

Yes they will. You'll never run out of potential customers.

A mainstream product requires a lot more than documentation and marketing (I assume you mean promotion). First of all, it needs a whole product, BlitzMAX is not. It doesn't have any strategic partners that could provide useful 3rd party software integration (like Photoshop, 3DS Max, Eclipse/CodeWarrior, Z-Brush, Subversion/CVS) and they don't seem to be working on these themselves.

Secondly they don't solve any mainstream market pains, and thus does not present the potential customer with a compelling reason to buy.

But lastly and most importantly, they do not have the third ingredient, market leadership either. They don't even seem to have a distinct target market segment for their products, other than wierd and wonderful people. It doesn't matter much at this point which market segment they chose to dominate, the Academic market segment or the Indie Developer market segment. What matters is they establish leadership quickly and unquestionably, and they put it in bold writing on the front page of the website.

Well the train of thought is probably fairly accurate, but the reasoning is probably a little off. Until the 3D module is out, and BlitzMAX as technology is feature complete, there doesn't seem to be much point in spending much time on documentation, that is still very likely to change in the mean time.

You got a point there.

Ok, Wave, so you're off to work on your docs, and I'm working on mine... You will most likely be done before I will, but at least there will be two more choices out there...

Russell

p.s. I'm typing this on my web-linked laptop while driving my car...with my feet. :)

I get the point ;)
About writing clear and concise, I'm not working on any new improved docs. I'll throw an exception for the beginners guide.

I'm not sure who said it:
"Give a man a program and you confuse him for a day, Learn a man to program and you confuse him for a lifetime"

Russell if you are working on improved docs I would be happy to help you. Mail me (see my profile) and I will give you my MSN.