Open up the Help manual in Wiki format

[Keya]

The Help file is seriously lacking in so many areas!!! especially when it comes to details and examples... it's really frustrating when you do the right thing as a programmer by taking the time to go through the helpfile to find the information you need, only to find it doesn't exist because the details are often so minimal.

And while we all know Fred has limited time on his hands it's also true that Purebasic users do have some time on their hands and that can be used to contribute, and many would love to if given the chance.

If it was simply opened up using the tried-and-true open Wiki format then users would be able to make contributions, clarify details, post specific examples, discuss specifics, etc.

The knowledge pool is our biggest and best resource as programmers, and it could only help expand that!

Fred you probably don't have any time on your hands to do this yourself, but that's ok - we could do it for you? There's a big pool of programmers here that can add some of their time to improving part of Purebasic - the helpfile - while allowing you to spend most of your time doing what we can't - programming the compiler. And of course it could still be hosted at purebasic, at http://help.purebasic.fr for example?

But we want your blessing of course

[IdeasVacuum]

Surely this forum already does that job, with the added advantage of being updated every day. If there is something missing from/wrong in the Help, you can report it on the forum and Andre will fix it. If there is something you don't understand, report it on the forum and we will all fix it.

[Keya]

But if the helpfile had the information that it should have then so many threads wouldn't even need to be created in the first place, and programmers would be able to find their solution without having to ask and wait at the forum. They are two separate resources that complement each other, but don't replace each other, and contributions to the forum usually don't make any change in the helpfile other than minor changes based on bug reports. But that doesn't allow for, for example, examples to be posted (majority of keywords don't include any example code!), and clarification on specifics.

For just one tiny example there is no mention in the ReallocateMemory page if it frees previous memory if it's had to move memory to a new area (turns out it does - i had to search the forum to find a post by somebody else who'd asked the same question - again this should be in the helpfile, but still isn't even though it's been asked at the forum). I could simply spend thirty seconds to modify the Wiki page to add something like "If the reallocation memory region had to be relocated the previous region is freed, so there is no need to call FreeMemory, and any attempts to read or write there will cause invalid memory access." From that point on nobody would have to go Googling, wading through irrelevant results and hoping that it's already been Q&A'd.

What about, say, handles or addresses? Go to a page like AllocateMemory and it makes no mention of whether the returned datatype is supposed to be 32bit Long or 64bit Quad, or the correct answer which is hybrid Integer for supporting both address types. Nearly every page in the helpfile that returns such a handle or address makes no mention of what size it should be, yet this is a fundamental part of the function, and it seems crazy to make a new thread about it, when it should simply be added to the helpfile once where it belongs and be done with.

[IdeasVacuum]

If there is something missing from/wrong in the Help, you can report it on the forum and Andre will fix it.

[Keya]

No, it's not at all practical to report thousands of missing items with a new thread for each one each time. I could try if you want but would probably find myself banned for flooding within 24hrs. I find myself asking questions on just about every page in the helpfile because details are so minimal and examples are often non-existent.

And then you get the same question asked in twenty different threads, simply because the helpfile is missing that 1 simple entry about something it should clarify, but doesn't. A Purebasic programmer can simply edit the Wiki page for it, and the problem is solved for all programmers in the future ever wondering the same question/having the same problem, boosting overall productivity for the programmer and the forum.

It's just not ideal to create a new thread for every tiny adjustment to the helpfile, it would be a flood if I reported every one of my questions.

Especially when Wiki format allows users to make those tiny adjustments themselves seamlessly, and allows users to make contributions without having to waste Fred's valuable time.

At the moment only Fred can edit the helpfile so it's a resource that's very limited, yet it's one of our most valuable tools as Purebasic programmers so there is no advantage in keeping it so restricted/limited and requiring Fred to spend so much of his valuable time doing something that us programmers could be doing (UNTAPPED RESOURCE!) - improving the helpfile, and allow him to get back to what we can't do - programming the compilers.

I know as im new here people are probably going to roll their eyes at any suggestion i make, but please consider the advantages and possibilities with an open mind, and weigh it up against the disadvantages if you can think of any.

[HanPBF]

Everyone can host an even free wiki in the internet.

The PB team would not forbid and can not forbid a collection of samples put online in a wiki like manner.

Wikis have the advantage, that everyone can submit posts and some operators can clean up nonsense.
Even the operators can do this by a reporting from other users.

And this is the problem of every wiki:
who maintenances it?
who sends code?
where should it be hosted?
will it be kept alive as long as this forum?

To have a wiki You need more resources in time and persons.

But in this forum, even beginners questions and no-sense-questions (like from me;-) are really quickly answered.

So, finally, yes a wiki is a good way of hosting information; but many resources are needed for that!

[Keya]

So, finally, yes a wiki is a good way of hosting information; but many resources are needed for that!

they already have the resources to host and moderate this forum?

[IdeasVacuum]

The Wiki format is not best suited for the Help because you will get some well-meaning contributions that are mis-guided at best.

Far better to get several answers to a question, usually quickly and with working examples, right here on the forum, and then see what else the discussion brings to light - the point being that this kind of "crowd" help is focused on your specific issue and there is, more often than not, more than one solution.

Thousands of faults in the Help? Sorry, that is not true. Help is being improved all the time by Andre, who invites forum contributions from time to time too. I think the Help is actually very good, I have contributed to it via the forum as have many others. You can do so here: Changes to the Help

[Keya]

The Wiki format is not best suited for the Help because you will get some well-meaning contributions that are mis-guided at best.

Wiki is easy to edit so if somebody makes a mistake it's easily and quickly rectified with either a minor adjustment or a complete Undo.

It's also easy to set various security levels so only certain users can make changes, etc etc. It's as flexible as you want it to be.

Far better to get several answers to a question, usually quickly and with working examples, right here on the forum

And then see the same question pop up in twenty threads over the next few years as more people spend time reading through the helpfile for a solution that should be in the helpfile, only to have to have to search, wade through all the non-related results, and hope they can find a match. Sorry but that is extremely time-wasting, counter-productive for programmers, and doesn't take full advantage of the resulting contributions/answers to the question.

Why not just answer the question once - as it should be - in the helpfile - then we won't even NEED to post dozens of threads about the same question!?

I think the Help is actually very good

It's ok and I don't want to take anything away from all the countless hours of hard work that Fred, Andre etc have already put into it which I am extremely thankful for, but it's just so lacking in depth - there are simply too many keywords which don't even have a simple example, and too many times I find myself asking very simple questions which you would expect the helpfile to cover. Fundamentals. Shouldn't have to be forced to ask at the forum for something that fundamentally should've been covered in the helpfile to begin with, and shouldn't be forced to Google through a myriad of unrelated results in the hope that somebody else has already asked.

It's all about MAXIMIZING PRODUCTIVITY (something that apparently isn't important to some but they don't value their time as much!), and the restricted helpfile doesn't at all tap into what is Purebasic's most valuable resource - its programmer pool. Why not take advantage of that!?

[IdeasVacuum]

It's all about MAXIMIZING PRODUCTIVITY, and the restricted helpfile doesn't at all tap into what is Purebasic's most valuable resource - its programmer pool. Why not take advantage of that!?

I don't think we are going to find a compromise between our points of view on this - that is also a situation which would be another issue for the Wiki, with someone making a contribution only for it to be deleted or replaced by someone else.

Yes, it could be uber-managed and rise to greatness, but that requires a lot of resource, a lot of time from expert Users doing boring Wiki 'house work' for free. That I'm afraid, will never be sustainable, no matter how well meaning the project is at kick-off. There have been many many initiatives of this kind, but they have all fizzled out.

If you want the help of the experts, it has to remain unchained, unscheduled, ad-hock as it is now - they can fly in and out of the forum when taking a break, with no obligation and no rigid rules about style etc.

[Keya]

A massive untapped pool of talent + Fred + Andre .... vs. Fred + Andre.

Do you think the disadvantages of allowing users to make helpfile contributions outweigh the advantages?

Do you think making dozens of threads asking the same question over and over and googling through unrelated posts in the hope it's already been asked is more productive for programmers than having it answered once, in the helpfile where it should be?

Do you think it's best that users aren't allowed to contribute examples, and keep forcing programmers to figure out how to use semi-documented commands themselves for commands that have no example code?

Do you think it's best to create a new thread every time something small is found or needed in the helpfile, rather than simply making the modification yourself?

Please think about it from a professional point of view where maximizing productivity, not having to re-do things that have already been done or should've already been done, and getting maximum bang for your contribution is important.

[Danilo]

A massive untapped pool of talent + Fred + Andre, vs Fred + Andre.

It's a commercial, closed-source product. Their is a boss (Fred) and his ants (Andre, freak, comtois, ...),
and only the boss gives the direction of the product and it's openess to the public.
With this commercial - closed system - model, only the boss decides the direction, not users of the product.
Users may make feature requests and wishes, but that's it. Just a dream, or a wish... basically it's just the people
who bring the money and sometimes ideas.
Bringing the money does not qualify you to voting, in this system.

[Keya]

and that's why I posted it in Feature Requests & Wishlists ?

It's a commercial, closed-source product.

Opening up the helpfile to Wiki != opening up the source code to the compilers - the helpfile can be open allowing for user contributions while PB can remain closed/commercial/etc. Best of both worlds?

Consider Apache's wiki for example, choc full of knowledge
http://wiki.apache.org/general/

[Danilo]

Yes, "Feature Requests & Wishlists" is about dreaming. There are 4.500+ topics and 28.000+ posts in this category,
beside the -maybe more important- 900+ bug reports in all bug forums.
PB actually got closed more over the past 15 years. The IDE once was OpenSource, but the boss couldn't accept
the IDE is used in ways he can't control. In response, even the PB SDK for library developers was reduced, and not
updated anymore. Yes, those guys are really paranoid. Especially about money, it seems. Closing all doors for 3rd party
developers is really paranoid - even if some scumbags used the IDE source for other purposes.

It's a big mistake, in my opinion. If you open up things, you can use great minds in the whole world, for your own advantage.
Closing things, reduces possible talent from 7+ billion to one or two men, basically.

[Keya]

Yes, those guys are really paranoid. Especially about money, it seems.

yes I dont like their business model as it doesnt provide much income to help grow the compilers, which basically = less money for Fred and less features etc added for developers (for example outsourcing some work to freelancer.com would be cool, very affordable too), but thats another matter