For the sake of keeping all happy, I'd suggest a two pronged approach:
- Reference part of Doc: keep it as is (for advanced use)
- NEW: add some simplified (=decoupled from any build logic) beginners-entry type of pages ...
I'd like comments from as many FB users as possible, on this issue ...
Well , I would definitely support that , I mean I have had my share of problems of trying to "wrap my head" around some of the stuff in the documentation and I think that FB ought to be as accessible as possible to the greatest number of users....
However , that said , then I think that that would be a huge piece of work and who is going to do it ? I mean I would perfectly understand if FXM said if you want something new then you will have to find someone else to do it - not to be negative but if you want something done besides what other people can be persuaded to deliver then be prepared that you might have to do it all yourself ( at least in principle if you know what I mean)..
But also accessibility and logic has to be built from the ground up - which is why a guy like me ended up being stuck with the TI-99/4A Extended Basic for so many years as I did. Much of what you need for accessibility is connected with the language itself. Meaning people making developing software these days (a general observation) generally tends to write their RAD software or programming language in a way that makes it extremely advanced to cater to the market of developers that are sitting making software for huge companies or software that got a standard Windows GUI. So for them accessibility is meaningless , at least it looks like that to me.
For programming language accessibility you need to a build a "skeleton" for your programming language that places the maximum power in the hands of the maximum number of users (including beginners) by designing core features to be powerful enough to be of use to the advanced programmer and yet simple enough to use and understand that they can be used by the beginner. And then to make stuff more advanced you must then extend the same logic that were presented to people with respect to learning the skeleton features of the language and also extend the whole programming language logically the along the same lines. By doing so then stuff will be equally accessible and useful to novice and and advanced programmer alike . Because all that the novice learned he can use with little or no change when becoming an advanced programmer and the advancing itself becomes so much easier and the advanced programmer can use even the "standard" "skeleton" features of the language also as part of the basic of his programing...
With respect to documentation that would also mean that the user will receive all information of *logic* necessity presented logically from the manual, meaning that when as basis the user receives all necessary information about "skeleton" features of that language that is *logic* *necessity* and then when something new is presented to the user in the computer language (or in "old" time a piece of hardware were bought that added the need for more documentation or language features) then the user will get all information of *logic* *necessity* presented in a logic manner extended to what has already been given of information.. Meaning , if you have the programming language and the hardware and the manuals that came with the stuff then you can also be sure that you also got all the information needed to use what you got :-)
The above were how I would describe the Texas Instruments approach to the TI-99/4A home computer and it's add-on the TI Extended basic.
However TI I lost in 1982 (?) to the PC market so this is PC programming days where for many reasons things are not as simple as that.
Anyway , though "ideals" may not always be something that one can live up to then one can try to approach an ideal as far as one can or wants to.
How close FB is to the "ideal" that I described that I simply do not know because I am so very new to FB and I got so much to learn but when I discovered FB only very recently I thought it a lot better than most other stuff for more reasons and among those reasons that it seem to me to be accessible to me at least to some extend - how far I do not know yet only time will tell.
So . as for the documentation (Wiki) in question then the "perfect" Wiki for me ought to follow the same ideal of "logic" with respect to presentation as described above...
Have a nice day / evening / night all of you whatever time it is at your place :-)
Making a *very accessible* very advanced programming language is not about making a programming language with a lot of commands/functions/whatever but about making the most powerful yet *logical* and simple to use language packed down in as few and as simple to use commands/functions/whatever as humanly possible (it's all about using superior logic from the ground up rather than make it up as we go).
(to refer to how I think *not* to do things I can mention a BASIC language I recently saw that bragged of having "Huge set of internal commands (1400+) to quickly and easily build any application or game" , ref. : main features of PureBasic : http://www.purebasic.com/index.php