PureBasic Forums - English

hi
there are so many post about this, but i thought it needs to be called again.

there is a big gap in the purebasic and thats just lack in documentation.

i'm so confuse about this!

how such professional tools can ignore this?!

just look other basics, dark basic(pro),blitz basic,power basic,ibasic,...
all of them sell more and more just because of documentation!
and you have the fully featured power full tool and do nothing about this.
adding more and more features is so good but after having a full range of documentation.
i mean officially not user dependent.
a refrence guide
a user's guide
a tutorial colection
i offered pb to so many of my friends but no one interested to buy pb just because this.
yes, learning pb during programming some software is fun and usefull but you must undrestand there is so many peoples that programming not for fun but for money their job or needs.
they haven't enought time to walk around and learn pb.

regards
Reza Behnood

I totally agree, I enjoy watching this forum, there is always something useful to read, but if you program "at work" you just can't waste hours to follow threads...

I am forced to use VB6 at work, and have to admit that most of the time is used to build the core program, not just serching the web for "tricks" to override the language limits or undocumented features...

I talked my collegues about PB, and they looked at the website, and the available demos simply don't make justice to the language, then looked at the on-line documentation, but any their question wasn't clearly explained there... Then said thet was better to keep on with VB6, at least you know how it works!!!

We have to admit that building a good manual is very time-consuming and wold make the PB price in-line with other bigger programming tools....

Perhaps we could start an on-line documentation project using tools like "wiki", where anyone can edit it in realtime, but this can just bring chaos!

So I keep watching the forum, in the hope that the next version will come with some good news. Perhaps Fred should build a team to share the various tasks needed.

Agreed.

So ..

.. let us do something about it.

Firstly, let us define what it is we want.

What, actually, is good documentation?

What format should it be? Are we talking tutorials? Re-organising the reference manual that currently makes up the docs? More examples? More explanation on examples? Should it include OS specific stuff? Which OS specific stuff? What can be done to give the AHA! insights that PB needs from time to time? Is the audience "Beginners to Computing" or "New to PB"? Are the docs generic, or is there one doc per OS? What language initially?

Etc.

Those who seriously want better docs, start posting ideas here. And if you are willing, also post what part you would play, what tasks you would be willing to perform.

I will do everything I can successfully do, up to and including writing the whole thing. However .. my skill levels mean that I would require some major input from the gurus. I am willing to play any role. Proof-reading, anything, to get the docs in place.

So who is game and what do we really want?

> a refrence guide
> a user's guide
> a tutorial colection

Paul's Resource Site is constantly mentioned in his sig but nobody seems to
take notice. Here's an excellent work-in-progress User Guide, for example:

http://www.reelmediaproductions.com/pb/ ... guide.html

His main site (with tutorials, tips, code examples, etc) can be reached here:

http://www.reelmediaproductions.com/pb/

These links have now been added to the Forum FAQ.

PB wrote:> a refrence guide
> a user's guide
> a tutorial colection

Paul's Resource Site is constantly mentioned in his sig but nobody seems to
take notice. Here's an excellent work-in-progress User Guide, for example:

http://www.reelmediaproductions.com/pb/ ... guide.html

That's the official PB user manual. Or would be if it was corrected and finished. Apply to Fred if anyone wants to help.

Hmmm. PB puts a lot of reliance on third party stuff (especially two sites) and also on the patience of users or potential users. I wonder what that costs in sales and dropouts?

Right, so now, from time to time, I go to the CVS and download a new batch of docs, or to realmedia.com and file/save as the guide pages. I wade through that and build my own docs, and then release them (complete with misconceptions and error) for gurus to proof read and fine tune.

*steps on soapbox*

RANT: I paid my $$ so that I could waste my time hunting down information across the net and on this board; And feel stupid asking questions on this board; And now I will put in more time (and I will) providing free labour in an effort to improve a product I like. At least so that I can use it. Whilst more OSes are added and outstanding stuff is not touched. Hmmm. PERHAPS: Improve the basics, and get more sales, and hire some staff. /RANT

*steps off soapbox*

*feels better for venting*

Okay, so now we start a documentation project. How would you, the gentle reader of this post, like it handled?

Just for starters, do you want a website with general access for those who want to access the docs, and additional access for those who volunteer to maintain the docs? Would a forum provide a way to supply sections or chapters and have them debated and fine-tuned before final copy/paste, or is a full-on sourceforge-type approach required (which last is unlikely to come from me)?

Are you willing to participate?
(Or would you just prefer to donate some $$ to Fantaisie Software so they can afford to get potential -the Fantasy bit - greatness converted to reality)

I agree on the "..improve the basics" stuff....
I think Fred is actually working on those things (improving the core engine) for the 4.0 release.. allthough it might be some time before it's released... Somebody shoot me down if I'm mistaken!! 8O

the docs are also something I was wondering about...
isn't André supposed to work on those?!? is it really that hard to write a couple of lines about a command which must have taken weeks to code?

anyways.. what I really think is lacking, are tutorial guides and beginner docs for the newbies...

I have felt the same way from the beginning. In many ways I regret the timing of my purchase. I continue to browse the forums but not with any great seriousness. I do hope that in the coming months that attention will be paid to this particular limitation.

Hopefully this thread is taken as constructive criticism and not a slight again a clearly capable development environment.

LarsG wrote:the docs are also something I was wondering about...
isn't André supposed to work on those?!? is it really that hard to write a couple of lines about a command which must have taken weeks to code?

My "official" job are the german docs (+ support), means keeping the german PB docs always up-to-date compared to the english ones.

I'm also improving the english docs from time to time, but I haven't the time + skills to write extensive descriptions + examples about every command. But I do what's possible...

But in generally you are right, the docs must be improved a lot.

The Purebasic docs should be revised and completed, that's a fact. As you can guess, it's very time consuming, and to be honest, it's not easy to write a good documentation for beginners when you know exactly how the internals works and when all is almost so obvious than it doesn't need even a single line to describe it. Another problem is the constantly growing number of commands which makes the documentation more and more hard to change. Did I say I have to do both english and french docs ? .

Ok, enough wining, I'm open to any suggestions to improve the docs. David already done a big job for a beginner tutorial and I will try to continue it to reach an usable state.

Fred, I have a potential solution.

After (hopefully) a few more people post here to put their views on what they would like or how they feel it could be handled, (and if my idea is not in tatters after that) I will post it here.

The catch is that as you say, you are too into it to see what some of us can't see, and some of us (like me) don't know enough of the technical stuff to provide what we need. And once we know it, we don't need it.

But I think the idea will hold together.

Here's my euro cent...

Why not create a new index on the forum called:

PureBasic Documents with sub threads for each library.

On those threads forum users can post examples and tutorials for each command, then with a magic purebasic program it could all be compiled into a manual...

This way the manual could be updated very quickly, tons of examples and how it works can be added with almost no time cost...

Fred would only need to concentrate on the Main and Really important parts, while users would make all the base work and give their input and experience into the manual.

There could even be a template for code, one for examples, one for notes...

Something like this:

;Library=2DDrawing
;Type=Example
;Description=How to draw a box on a window
;OS=ALL

bla
bla
bla

I second Num3 motion for PureBasic Documents with sub threads for each library.
It would be of great help to find quickly examples for each command.

Or maybe something along the lines of the fantastic PHP online docs? The online docs already exist for PB just in an unfinished state, just add the facility for the public addition of notes/examples (a'la wiki) etc. just like this: http://www.php.net/manual/en/ Then we could all contribute. Surely there is too much work gone into the online docs for them to be disregarded and to start again with a new forum heading?

@Kale, your point is also very valid, but we must not forget about the people that do not have easy internet access.

So it would also have to be distributed with PureBasic for offline consultation or available for download...