documentation

[Paul]

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

"The" Resources Site
http://www.reelmediaproductions.com/pb

Like I said, it was available but never used. It makes much more sense anyway to the the CVS since it is already in place and it is what is used to compile the official Docs.

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.

What are you using? I use WinCVS and it takes about 15 seconds to download the entire CVS tree. (and NO, python and whatever else are not required). You do all the work/changes on your computer then hit update and the changes are sent.

[freak]

[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 *

I'm just telling my opinion. I don't stop you from doing it.
If you want to, go for it.

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.

That is exactly what I wanted to point out. This is not true.
Paul had exactly that on his site some time ago:
An online version of the docs, with the posibility to add examples/stuff with
just a mouseclick.
It died, because nobody added anything.

Just look at the work of Andre and he's only one person.

Andre is not just a user. He has been a friend of Fred even before PB existed, and has helped ever since with the translations.

Btw: If you don't want to invest the time to set up cvs access (which is
described well by fred and just takes 10 minutes btw), how do you
seriously want to improve the docs?

------------------------------------------------------------------------

Allright, I'll shut up now. Do whatever you want. If it leads to improvements,
I will be happy to be proved wrong, if it doesn't... well, then it will
just be one of many...

Timo

[mar]

Code: Select all

fred: 
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. 

Why there is no actual pdf-version?
(Also there are some too long lines in the docs.
... should be corrected befor converting to pdf.)

For me its unclear why this discussion is such a big thing.

I totally agree with freak's comments

can't read anything further of this stuff /rem next time skip this/

marcus
--- I'll try to continue contributing some little stuff for the docs ---

[GedB]

I'll second the idea that CVS is not good for documentation. The workflow is all wrong.

In a Wiki environment, if I come across something that I find inaccurate or lacking I hit edit and make the changes. It takes 5 seconds, no bother at all. Myself, or anybody with a browser, can do it. I've contributed on quite a few Wiki's myself. The effort of contributing to a Wiki is about the same for contributing to a Forum.

For CVS I have to download a client, log in. Hassle, hassle, hassle. I tried CVS once, didn't like it, didn't bother.

I think the best examples on how to do this are Wiki and the PHP docs.

[Dare2]

For me its unclear why this discussion is such a big thing.

Its fun?
It is a way for some to express themselves on a subject?

@freak
The hypothetical conversation was not aimed at you in particular, my apologies if it offended. The posts on this board/forum/subnet have more than a few grouses at people who have suggested something.

I agree, everyone is entitled to their opinion. I respect yours. It also worries me because if the people best qualified to help with a manual shy away from it, that CAN kill the project. Or render the end-result pointless. See below.

I have been wondering at the resistance to this.

It may be that there is now a proposal to add an extra workload, which is not of their making, and some people are unwilling to take it on. But they are also unwilling to look bad if they don't pitch in. (Not a criticism, btw). I can understand the feeling of being placed in such a position.

If a manual is written using an open method and it contains errors, posting a correction is surely not more cumbersome than posting help for someone on this board?

@Paul
hehe. I knew which site you meant, just wanted to let you promote it. I take it the wiki will not be revived?

I used my browser to browse the cvs. I had no idea there was such a thing as a winCVS. (lol - This from the guy who is about to offer to write the PB manual).

- - - - - -

Okay, as I mentioned in my first post on this thread, I am willing to write a manual. Not the best candidate, I know, but a willing one. The manual will be basically useless for anyone unless some qualified people verify and correct it.

Peek
Grabbing an eyeful when you said you wouldn't. In PureBasic the following peeking is recognised:

PeekL - A long peek. What you saw grabbed your attention.
PeekW - A wordy peek. What you saw forced an exclamation.
PeekB - A byte peek. Almost a wordy peek but you managed to bite your tongue instead.
PeekS - A rapid series of peeks.

Poke

Click here if you are of legal adult age in your country of residence.

After writing the manual I will submit it to whomever gets these things. They can then submit it back with suggestions, and so on.

Whether I write it or someone else writes it, the main thing is that it is maintained thereafter, and any released form is easy to access.

I admit a preference to a forum or wiki approach. However, internally things can be done by carrier pidgeon, CVS, wiki or ESP for all I care, as long as they are done, and we get some better docs.

If the CVS is the only way to get qualified help, so be it.

Would this suit the inner circle?

[Behnood]

hi
i can't understand why all peoples here think about purebasic like a opensource project!:)
anyone can help to improve it but i think fred must arrange and moderate the whole system.
making a good and full range documentation is like a good investment.
i'm sure that right now fred and all his guys spending their time on adding more and more commands, more 3d stuffs, more everything else but documentation:)

just let the improving cycle of the code to be relax for a while and complete the documentation then you will see that adding and changing in future will be easy.

if you want to see what is a good documentation look at vb help system! sometimes it is good to learn from opponents.
every command clearly explained with keeping in mind that not all programmers are geniues!

full syntax
explanation of parameters
notes and remarks
some examples
related topics

and i think this is good enough for a pattern.

by the way fred you must begine to make this revolution if you want purebasic be alive and grows well.

regards
Reza Behnood

[GedB]

anyone can help to improve it but i think fred must arrange and moderate the whole system.

Personally I would rather Fred spent his time improving the compiler.

Having Fred manages everything else as well not only takes his precious time from the activity, it also creates a bottleneck.

I use Visual Basic and Java at work. The reference books I use are rarely the ones provided by Microsoft or Sun. I think the principle is the same here. If a langauge is to prosper there needs to be more than just the core product. You need to have all these other projects going on as well.

I think the best example of this is jaPBe. I used to consider PureBasic's editor a serious limitatation, but not anymore.

I'd like to see something similar for documentation.

[Behnood]

hi
what is good for us isn't good for purebasic always.
i said fred must do that cause fred own the purebasic. so he must decide what he wants to do with it.
purebasic needs to has good documentation if it wants widely use by more than just hundreds of peoples.
adding more and more features before making a complete documentation just make the purebasic more and more complex and far from new customers.

the problem behind all these is thinking about this product as a opensource project!

vb and java have so many third party documentation cause they first became widely used.
regards
Reza Behnood

[Kale]

i can't understand why all peoples here think about purebasic like a opensource project!

We don't! Its threads like this that discuss ways of helping Fred & Co. out by banding together and contributing. Personally i have no problems with the documentation and I would like to see Fred carry on developing the core, but I realise others may struggle a bit with it.

[tinman]

I intend starting working again on the user guide, but it will probably only be about an hour per day. If anyone wants to help then email or PM me, or post here and we can get some co-ordination.

And for those complaining about CVS being awkward to use, you really should look at TortoiseCVS (http://www.tortoisecvs.org/) - it simplifies things to such a degree that I've only used WinCVS once in about a year.

[Num3]

@Tinman,

I already asked Fred CVS access so i'm available to work with you.

I can´t give much of my time, about 1 hour too, but 1 hour is better then nothing, and 1 hour from me plus 1 hour from you is already 2 hours, so...

[Dare2]

@Behnood

Maybe it is just another way of applying, um, pressure? If you owned PureBasic would you want your docs (and reputation) in someone else's or a committee's hands? Or in my hands. lol

But that is what you get unless you take action yourself. Or someone safe does. So ..

@tinman

Thank you.

@num3

And you.

If a rookie can help, count me in. (I am away on business for 3 to 4 days, will PM you guys on return if that is ok and if you can see a role for me).

[Num3]

@ All already working, just edited 3 commands.

@Tinman, Tortoise is excellent and very simple...

[Andre]

Rui, I've already seen you started your work with first contributions.
Some suggestions about the rules to follow (to get nice manual with nice layout) you will get on the CVS mailing list.

@All: Everyone who is willing to help (but don't like the CVS etc.) can post small code examples (showing a specific PB in action) also here, as well make some usefull comments what notes should be added to a specific command. (Of course its also possible to send me something per email, as this is already an usual way for several german PB forum members.)

It's not new, that I look at all forum threads for useful codes to add to the code-archive. I can also use such postings for improving the manual.
Everyone can discuss about a alternative system of contributing to the docs, but this way is the easiest one and everyone can start NOW....

Maybe Fred can add a new forum chapter for the contributing to the PB documentation. Would make things a bit easier to follow.

[Blade]

Despite "freak" things are going in a good direction...
This make me wanting to buy PB (at last) and contribute!

Now please make a new forum chaper as said Andre, to not disperse the contributions...

And don't annoy Fred, he has to add new features to PB !!!