I know you've all heard it before....

[koehler]

You had the opportunity to read the 'complete docs' online at any given time.

Sorry you didn't do that. The docs you downloaded, are always online.
The docs distributed, are 'exactly' the same. Only in compiled html format. - np

I'm sorry, but what bearing does that have on this? I'm well aware that there are docs online, go look at them and you'll find that there are some that show blank pages, some show examples, many do not.

The point is, I could go back to any Basic, C, Forth, Pascal, etc, etc, text I've ever owned, and find not only a description, but an actual example for every command.
This has nothing to do with whether the online docs are the same as the offline ones, but that the docs themselves are woefully incomplete.

One of PB's main advertised features is "Huge set of internal commands (600+) to quickly and easily build any application or game".
I'm sorry but quickly or easily is not really how I would see PB at this time, as a non-expert PB user.

Thats sort of why the Official docs should be focused on. People shouldn't -need- to use the forum for basic questions. And, there used to be a time when people would actually read texts/manuals to get the big picture plus the details. If you prefer to hop-scotch around playing with examples, then fine. But expecting everyone else to do that, and expend 4-5x the effort and time to get an understanding isn't exactly efficient.
But its a great excuse for not having decent docs.
"People who need docs are stoopid. Everyone should prefer to browse the available docs online, and search for example to answer their questions. Being methodical and reeding is old-school, get with the times"

Blitzbasic won't do what PB can do, however VB may be able too, has excellent docs, and is not going to be as quick.
Sigh......

[NoahPhense]

I don't know what to say. I'm used to the way things are.. but even if I
bitched about it, I don't think it would change anything.

Mostly, and I'll place money on it.. that when people need help, they
make a post, and people get on it.. I know that's not what you're looking
for.. you're looking for full docs. Well, an example for every command,
that does not exist. But, if you have the time, why dont you head up a
group that will do just that..

Im not trying to be smart.. I'm just bringing a little reality to the
darkness.. pretty docs are not -- and will not come over night..

And I wouldn't hold my breath waiting for them.. I guess mostly
because I've learned to move on without pretty docs.. and that's probably
because I've used worse... I have no complaints at this point, these forums
are kickas$, and there are a lot of very tough programmers in here that
shoot out answers without even thinking about it..

l8r

- np

[Shannara]

[quote="koehlerOne of PB's main advertised features is "Huge set of internal commands (600+) to quickly and easily build any application or game".
[/quote]


What the??? There are not even close to 300 commands in PB... how did 600+ creep in there? Or is the docs that severly lacking?

[kns]

It's not "pretty docs" but rather proper documentation that logically introduces the language elements, including the equivalent of a User Guide. There is no reason why a commercial package should ask the users to tough it out - and quite frankly the help on the forums is of mixed quality. Further much of the example code is of varied quality with respect to ideal programming practices. I have seen very nice readable code posted (the ideal), but by and large we're presented with difficult to read and uncommented code. Now, I don't expect anything else from the users because they are not being paid to create logical tutorial quality code. People are sharing what is available. And 'yes' some individuals have proven to be remarkable sources of information, freely giving their time.

Now, is PB meant to be a hobbiest's language or is the intention to appeal to a wider audience?

It seems that I'm not the only one who believes that the typical user prefers to have standard documentation - hence their existence for most commercial projects. I'm in full agreement with Koehler!!! The truth is there is no argument. The state of the documentation must change (in time). The current state is no where near an "efficient" use of user time.

[Dare2]

The whole discussion on documentation is very sad.

The idea of user-created docs has two flaws: (1) A user who needs docs doesn't have enough information to write the docs; and (2) A user who invests time writing docs loses opportunity income, ie, the same time spent productively elsewhere could earn money.

I know, because I have fallen into that trap.

Too much time was spent on attempting to writing docs and there is still nothing to show for it. PureBasic has had no benefit, nor have the users. I have had a benefit (increasing understanding) but the yield was low.

I have had a far quicker learning path through these boards. And that is also sad.

Ultimately the responsibility for docs, and the definition of "sufficiency", lies with PureBasic.

A lot therefore depends on what the PureBasic team consider to be important. The goal. If it is creating a product and business, eventually the documentation thing will be addressed. It will have to be. But if not, if the goal is geek-ish, then there is very little motivation for wasting time on boring stuff like docs. Those in the know, know. Those who don't know have to rely on goodwill and generosity on these boards - fortunately there is a great deal of that at the moment.

Anyhow, to get better docs we had best think of a great way to motivate the PureBasic team.

* checks gonads - phew again. *

[Shannara]

Well, there is the possibility for someone to create a book/guide, "The Unofficial Manual for Pure Basic". And if they were to sell it for a certain amount of money (and if people was willing to buy..), then it would be time well spent and people other then hobbyists would be able to use the language in an effecient manner.

Now we all know there are commercial products out there created in PB, but that's not the point. In order to make a commercial quality program, you would need (in PB's Docs current state) extreme help from the forums. If there was nice documentation out there somewhere, it would be quicker and less frusterating for creating any kind of apps with PB.

Just my two cents.

[Pupil]

What the??? There are not even close to 300 commands in PB... how did 600+ creep in there? Or is the docs that severly lacking?

Are you talking about the Linux version?? Because there are 600+ commands in the windows version, just check the file 'Purebasic\Compilers\PBFunctionListing.txt'' for a complete list over all the commands available(if you have userlibraries installed there will of course be more commands in this file).

[The_Pharao]

why not set up something like wikepedia for the documentation?

[Kale]

why not set up something like wikepedia for the documentation?

This all has been discussed before.
viewtopic.php?t=9429

[blueb]

It's worse than I thought.

Thinking that an author of a book would need people to buy his book, I decided to see how many people were using this forum. You would assume anyone who purchased PureBasic would also belong to the forum... after all... the manuals are nonexistant.

Hmmm....
- 985 total members
- 586 members with more than zero posts

I figure if a person posts more than 5 times they have purchaed PureBasic (the first few questions are just to see if PureBasic does what they need)

Well... only 385 people probably own PureBasic!!!! (more than 5 posts)

Hardly enough volume to consider writing a book.

What we need to do is get the word out!

Fred first needs a lot more users, then we can worry about documentation. (Which I think is quite good , considering the user base)

--blueb

[LarsG]

Note that there that many users on *this* forum.. There atleast one more forum with a "substantial" amount of users...
But still.. It probably won't make much difference... :p

[Karbon]

There are more users than 350ish for sure but it's still not to the point at which a book would be commercially successful..

[Shannara]

Well, yesish and no-ish The startup fee for a book (POD/hardback) is close to $1,000. Each book would cost roughly $30 - $40 for 600 pags. The author would get about $10 per book.

$10 x 350 = 3500, if anybody would find such a thing usefull It covers startup with a bit left over for another edition (when pb matures..). And the cycle continues just like those nice mutliple edition VB books... whee...

Also, I didnt know about the functions.txt list. Wish that was the current docs as the docs does not contain the everything in that functions.txt file.. agh!

[Karbon]

Are those numbers real or your best guess?

It would surprise me if there were any publishing companies that would publish a "real" book who's entire worldwide audience is less than 1000 people. That and $3,500 over the course of months and months for the time it'd take to do a proper book sure isn't much. Again, I don't think it would be commercialy successful but that doesn't mean it's a bad idea

Who knows though - might be worth a try!

[Shannara]

Real numbers. $900 for both eBook, paperback and hardback editions, multi-colored covers, with ISBN and copyright registration. LOC number, etc. These are orderable through Amazon.com and B&N. Mind you these are PODs not the brick-and-motar publishers. So they are printed on demand and do not have the obsurd (sp?) limitations that traditional publishers have. If you have the money to fork out, they will publish (just look up PODs on google ).

I have been researching PODs for almost 2 years now for other ventures and publishing deals.. Never thought of writing documentation for a language which no have docs. (but a nice-ish help file).

Possible, but would anybody want to take the time to do so? I mean, with PB changing every few months, it would be out of date before the first copy is off the printers..