PureBasic Forums - English

@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...

I understand. Although here are ways of coding and interfacing with existing PHP apps (e.g. forums/online help, etc.) to 'automagically' spit out html pages which have been dynamically generated from a database for inclusion in an offline version. You'll need a PHP guru but i have seen it done where i used to work.

PHP manual is an excellent example of well structured and formatted info, 2000 pages long, growing online since 1997.

A very nice feature on their site is allow readers of the manual to contribute examples, caveats, and further clarifications from their browser, and until the notes have been approved and incorporated, they can be viewed in their submitted form online.

With one person (or one team) working as editors to incorporate that feedback into the main text of the manual, is possible to mantain the quality of the code examples.

There are Paul's, Andre, BluezNl (thanks them!) and a few other PB resource sites, but we need a good manual online, and something like this could be the way.

Okay, a proposed solution.

It is a living document, with snapshots taken and released from time to time.

The document is developed on a dedicated forum or a wiki. Let us say a forum.

The forum is divided into document groups.

Each doc group has a topic for the section, and the first few posts in that section are the reserved for the actual doc.

All other posts are suggestions, ideas, questions on the section.

The groups/documents are:

Tutorial
This is a basic intro to programming concepts and targets newcomers to programming and very old hands who last coded when the abacus was the machine and who now have to learn new tricks like OOP, events, etc.

So it would explain variables, etc, and events, and etc.

Manual
The manual is the guts of the doc, and goes into detail about things. This is where things like *ptr and ptr being different variables is explained, and the actual differences in how PB deals with a *var versus a var (if it does so) are explained.

The manual is organised along logical groupings - the basic folder structure of the code archive from www.purearea.net is a good example of this grouping. Perhaps it should be used as the structural template for the manual, as it is, well, logically organised.

Reference
The reference section is similar to the current help and manual, but the groupings are dropped and things are in alphabetical order.

Each entry has it's own example, even if this is a duplication of the example used for associated code. It has a reference link to the more detailed manual, and "see also" links.

Appendices
Lists of things like PB constants
OS significant things

- - - - - - - - - - -

The documents outlined above will take a lot of work. But it can be done quickly.

Firstly, the "document posts" are authored by a team, each having access to edit those posts. These "posts" are set up when the forum is created and in the initial stage they will merely be *RESERVED*.

Posts following the document posts are suggestions, queries, ideas, etc, by interested parties.

Everyone can help. Grammer, spelling, ideas on how to explain concepts, etc, are posted here. Posts by newbies and slowbies and dare2s will bring out the confusing parts of the documentation. Comments by experts will ensure the code and tech detail is well explained.

The "team" can adjust the "document posts".

The project is overseen by the Fred and his PureBasic team.

Authors are volunteers good at explaining things, not necessarily good coders or PB experts, just so long as they can understand the concepts and explanations of the gurus, and explain them to the tyros.

Everyone who wants to can go to the board and read, and make comments.

- - - - - - - - - - -

Snapshots are taken from time to time. The "document posts" are extracted and html created.

This html is can then turned into .chm, or .pdf, or .doc, or .whatever.

The document becomes a part of the download.
It also becomes the online docs for PB.
And it is downloadable as a sep file in the supported formats.

When the snapshot is taken, all posts are cleared from the forum, save the "doc" posts, and the "living" document lives on until the next snapshop. And then lives on.

- - - - - - - - - - -

Once started, the benefits are there for everyone. For PB because the documentation is an important part of the product.

For participants and volunteers because as they help, they learn and become gurus themselves. They become good. Having to explain something clarifies the mind and improves understanding.

This in turn lifts the core expertise of the PB user base.

- - - - - - - - - - -

Notes:

It is PB documentation, not 3rd party user library documentation.

It does not cover user libraries. (Bet many of you are so used to these libraries that you've forgotten you use and depend on them - and the newcomer wonders why things don't work)

It is not win or linux or AmigaOS documentation BUT there should be sections for OS significant stuff.

The first posts per thread/topic are used as:
1. "Current Final" or best so far documentation.
2. Directives to document building scripts as to where to cross reference, etc.
3. Working draft, cut and pasted to (1) "Final" from time to time.

4 onwards. User contributions and ideas.

- - - - - - - - - - -

I run something like this on some intranets (which have nothing to do with programming but do have process and application of process requirements).

Simple scripts do the snapshots, creating chapters, sections and indexes, clear posts, etc, on demand.

The people in the intranets using the approach are all more clued up and effective than those where the intranet managers decided against the approach. Newcomers have good official docs, and can visit the living doc to get up to date info. And post their confusions, to the benefit of the next doc release.

I believe it would work here.

The bulk work is the setup. Thereafter all you have is modification (sometimes major, mostly minor) and steadily improving documentation.

We need a forum, pref by PB. If not possible to provide by PB/FS, then I will provide one on one of my sites. But pref PureBasic does - and uses their bandwidth

Fred and team also need to decide on who the official authors are. Again, good explanation is better than good coding.

Finally - the project is egoless and without hierarchy, save for Fred and PB team overseeing the thing.

Everyone makes good use of their talents. Advising on grammer is as important as advising on code. Nobody needs to prove how good they are, the only success is if the doc does what it should - teach and help people.

Sorry to sound too negative, but this doesn't work.
Sveral threads like this one have been here in the past. All there was always a big
discussion on how things could be done efficently when lot's of people contribute, blah, blah, blah...

The reason nothing came from it, is that everybody is good at talking stuff like that,
and having *great* ideas, but when it comes to actually doing the work, nobody does it.

There doesn't need to be a new system to manage this. The actual one
allready does that, the only reason nothing happens, is because nobody helps.

All docs are publicly avaiable. (http://cvs.purebasic.com/)
And everybody can contribute if he wants to.
Those who just want to help a little, can sent their improvements
to somebody with cvs access (Fred, Andre, Berikco, me, ...).
Whoever wants to help more often just has to talk to fred, and he will
get full access for sure.

You see, the problem is not the system. It does a good job. The problem
is that nobody helps. So it is left for those who do the coding anyway.
And there is the old problem: "good coders write bad documentation".

So... if you want to help, stop coming up with *better solutions*, and
actually do something.

My 2 cents...

Timo

Heya, Freak. Point taken.

1 cent change given.

I agree that talking is easy. But maybe something has started here. Why don't we give it a go?

So, do you agree that there needs to be a manual as well as a reference section?

And if so, do you agree that organising the manual along the lines that the code archive has been organised would be useful?

The reason I think the code archive organisation would be good is because it approaches things from the viewpoint of the user ("How do I do [something] in windows?" *opens windows folder*).

Freak's answer seems a bit rude, but it's mainly because he followed such thread since a while now, and it always ended to the same point. The actual system is build with a CVS which allow easily the cooperative work and if anyone want help and revise some part of the doc, it can gain access to the CVS tree.

The file format has been designed to support different output, so the same files can be used to generated RTF, CHM, HTML, Multiguide etc.. in one click.

What I see for now: one easy example for each command would be a good start. May be more cross references between commands. Reorg the few commands which don't have the good placement (like Peek/Poke which should definitely be in the memory section).

Anyway, a php-like online docs (WIKI based ?) sounds a nice idea if it's correctly moderated.

the problem is not the system. It does a good job.
The problem is that nobody helps.
....
There doesn't need to be a new system to manage this.

With 900 registered users on this forum, the reason for "nobody helps" could be simply that CVS is a very old tool, confusing and not friendly.

The newest example in PureBasic-CVS] / Sources / Examples is 8 months old, the rest are for PB 3.60, and the Sprite examples are for PB 3.20! (20 months old)
Why? May be because nobody feels confortable with it.

I have access to CVS since august 03, and don't use it because I found it very unfriendly.
A try to another system like a strongly moderated php-like online docs sounds far better.

My 2 euro cents...

With 900 registered users on this forum, the reason for "nobody helps" could be simply that CVS is a very old tool, confusing and not friendly.

I must admit i hate CVS. I can see its value in huge coding projects but IMHO its too unfriendly just for docs.

I must admit i hate CVS.

Me too!

We have 900 registered users here, does that equal to 900 documentation writers?
Certainly not. Most of them are just users, and will never contribute anything,
even if there is a oh-so-comfortable system for it. Just look at the memberlist,
265 have never even posted a single line here, what makes you think, they
will write documentation?



I don't see how cvs is unfrendly. Well, ok, maybe you'll need to get used
to it, but it is a very powerfull system to manage such things.

CVS may be old, but it is good, that's why it is still heavily used in open
source projects.

If you are really honest to yourself, do you really not do anything on the
help, just because you feel *uncomfortable* with the cvs?
Or *might* there be another reason?

Let me give you another example: the german forum has a FAQ section.
The concept was, that everybody can write articles for it and PM them to
the moderators, who will post them there.

Nothing happened. (there was a new post every 2 month or so)
Soon, the people started to complain, that this system was not good, that
they don't want to send stuff to the moderators first, and thet it would all
be much better, if everybody could post to the faq section directly.

The system was changed, everybody has access now.
Guess what, still nobody posts there. (except for accidential posts in the wrong forum)
That's because people were good at talking in the first place, but now they
are just too lazy to actually do something.

Nobody can tell me, that this faq system is too complicated or uncomfortable.
That can't be the reason.

My original point still stands: Writing documentation is work, that's
why almost nobody does it (at least not seriously over a long time)
People are just too lazy (i don't exclude myself from that)

Bottom line:
1)
I won't spend any time setting up a cool new system, that is not going to
be used anyway. If one of you has to much free time on his hands, feel
free to do so.

2)
Purebasic provides a reference. I agree, that a seperate documentation
could be usefull, but i just don't see who would write it.


My guess is, that this discussion will go one for a little more time, some
more ideas will pop up, maybe somebody actually *does* something, and
creates a site do such project, but in the end, it will die, as did all the others.

Sorry to sound negative again, but i've seen this before (several times)..



no euro cents this time, gotta save my money

Timo

freak wrote:no euro cents this time, gotta save my money

hehe.

Freak, if you're right and nothing happens, what was lost? Nothing.

But if you're wrong and something does happen, what a gain!

So be supportive if nothing else, and next time I'm in Europe I'll buy you a beer. And you can buy me two. XXXX or fosters.

@Fred

Good to hear your thoughts on changes.

You have a potent product, and potent documentation won't hurt the cause.

Revising the existing docs and improving is good. There is not much wrong with them, there is just not enough of it.

When you say that a php-type wiki is a nice idea, does that imply a go-ahead? If so would you want it third-party or not? And if 3rd party, would you be prepared to nominate the administrators and moderators?

I have to agree with Freak.

Regardless of how many users you have, work is work... and to top things off, you would be doing other peoples work.

No matter what system is put into place, people will find excuses not to use it. The current system that is setup uses CVS. It works but what do we hear? ... it's old, it's hard to use, blah, blah.
Everyone says the system used on the PHP site is the best. Guess what, the Resources Site had that system setup for PB but ended up removing it because no one used it either.

It's easy to talk big but when it comes time to actually do the work... well

Hmmm

You are just after a beer as well ...

* thinks: Maybe I should knock this too - that way at least I'll sound like a hard worker *

Paul, which "resources site" had that? Maybe it can be resurrected?

On the CVS and current set-up:

I have been pulling stuff out of there every few days. Check the logs and find my footprints.

I have a small percentage of it downloaded. It is taking some time.

Now compare that with getting the code archive. One download and an unzip.

Which was easier to do? Which was quicker?

In fact, unpacking the .chm is quicker than accessing via CVS.

And how do we get suggestions implemented? The idea is to message the people who can. Ask them to work harder.

Okay, look at the responses of some of the influential PB people (IPBPs) on this board. Really encouraging.

[User]Excuse me, I have an idea ..[/user]
[IPBP]*Groan* not again! *snap* done that before *grunt* bothersome *growl* use the search ..[/IPBP]
[user]Sorry .. I think I'll just go away now ..[/user]

* yes, exaggerated - but how much *

Can't understand why Dare2 proposal for support gets rude responses.

We have 900 registered users here, does that equal to 900 documentation writers?

No.
Does that equal to 0 documentation writers?

Reality is that PB lacks of good updated help docs.
May be some PB regular contributors can aport his work, if the way to do so is friendly.

I don't see how cvs is unfrendly.
...
If you are really honest to yourself, do you really not do anything on the
help, just because you feel *uncomfortable* with the cvs?
Or *might* there be another reason?

Might be a lot of reasons, but with CVS installed, messages like "TCL is *not* available, shell is disabled"
or in Authentication, where is supposed you must enter "pserver", this option is not available.

And in other instances, a previous CVS install asks for some Python sources. ???
That's enough reason for me.

Well, ok, maybe you'll need to get used
to it, but it is a very powerfull system to manage such things.

Too powerful to manage a help file.
The time that I need to get used to it, I prefer to devote to do more pleasant things.

It's easy to talk big but when it comes time to actually do the work... well

Yes, It's very easy.

We have 900 registered users here, does that equal to 900 documentation writers? Certainly not. Most of them are just users, and will never contribute anything, even if there is a oh-so-comfortable system for it. Just look at the memberlist, 265 have never even posted a single line here, what makes you think, they will write documentation?

I think thats a bit cynical, I know you've heard it before but if it was easier to contribute something then more would do it. Even if two or three people contributed to the docs on a regular basis it would grow fantastically. Just look at the work of Andre and he's only one person (i think )

If you are really honest to yourself, do you really not do anything on the help, just because you feel *uncomfortable* with the cvs?
Or *might* there be another reason?

Nope, i just don't like CVS, its overkill for the PB docs.

My original point still stands: Writing documentation is work, that's
why almost nobody does it (at least not seriously over a long time)
People are just too lazy (i don't exclude myself from that)

Not really, for many people coding using PB is a hobby (including me) and if contributing to the docs was as easy as opening a web page, entering an example or text then hitting submit, then i suspect many more would contribute. I realise however this is mega work and maybe unworkable for now but i still think its a good idea and maybe possible for the future.