Documentation?

[MrTAToad]

All you need to do is register, and then you can edit to your heart's content

[Cliff3D]

Its in the The project maintenance area section...

Ahh...errr... that's a pretty great example of what I was talking about wioth regard to "point of view".

I am prone to being a bore typing lots of stuff, but I have been kinda busy today so rather than bore everyone I'll wait to be asked to explain my POV, as a GLB newbie, on documentation using this specific item as a great example.

It boils down to the difference between task orientation and "what does this do?". Existing documenation leans heavily on the side of "What does this do" rather than "How do I...?"

[XanthorXIII]

I'm of the mind that documentation talks not only about the structure of the commands but also gives good examples(Read Several) of how to use that command.
Although I think the website should spruce up on the tutorials section. If anyone knows some really good tutorials. That would be awesome.

[Bursar]

It would also be useful if all related commands were listed next to each other. For instance anything relating to sprites (such as loading, displaying, rotating, collisions) should be grouped together as trying to find them in the help file is a bit of a mission.

Obviously as a newcomer around these parts, I'm expecting some flack for my next suggestion, but... maybe some of the commands in GLB should be changed. Looking at the help file I can see a rather long list of commands starting with NET. Perhaps other commands should follow suit - SPRITELOAD, SPRITEDRAW, SPRITECOLLIDE, SPRITEFREE (rather than GENSPRITE) and so-on. With a similar naming convention for other groups of commands.

It would certainly make trying to locate commands in the help file much easier, but obviously may cause some compatibility issues with existing projects!

[MrTAToad]

The commands on my website are grouped into the relevent sections, but on the wiki they are just in alphabetical order.

[Cliff3D]

It would also be useful if all related commands were listed next to each other. For instance anything relating to sprites (such as loading, displaying, rotating, collisions) should be grouped together as trying to find them in the help file is a bit of a mission.

Yes, definately, but not just commands IMHO.

The Wiki isn't MrTAToad's baby, it was produced by someone else as a place for the GLBasic community to adopt. It'll only work if WE piut the effort in to learn how to edit the Wiki and add a bit each ourselves, IMHO. WE can make it what we want.

It'll be a bit sad if only newbies ever edit it, but on the flip side - who knows the documentation is lacking more than a newbie struggling to find his or her way? Who best to fill in each gap in documentation as it comes along than someone to whom that revelation is fresh? Wikis live or die by their user base. Either we make it good and helpful, as a large group, or we individually wait for Kitty Hello and MrToad to do all the work (ish).

Alternatively, if the BLBasic gurus could edit the Wiki to add an explanation instead of putting their answers here, and then link to the relevant page in the Wiki, that might kill two birds with one stone - albiet being harder work for the Gurus might mean they feel less inclined to answer

[MrTAToad]

I would like to more or less transfer everything from glbasic.un-map.com to the wiki - it would make editing and changing things so much easier

[okee]

MrTAToad I'm willing to help, although still getting used to GLBasic i do know basic very well
Could start on the string commands with a few examples for each command.

[Cliff3D]

I would like to more or less transfer everything from glbasic.un-map.com to the wiki - it would make editing and changing things so much easier

That sounds like an eminently sensible starting place, and something that anyone should be able to help with, given a few minutes to get to grips with "How to edit the Wiki" (I imagine). I don't do a lot of Wiki editing but - how hard could it be?

MrTAToad I'm willing to help, although still getting used to GLBasic i do know basic very well
Could start on the string commands with a few examples for each command.

I think any and every help would/should be appreciated.

I wonder - should we just try to copy stuff across, amending where we feel able, or should we follow okee's example and pick some specific area to help out in, announcing it in this thread?

[MrTAToad]

If people want to start adding examples then they can...

If you want to add a command, then take it off my website, and slightly format it for Wiki use - you'll see the current layout I use if you look at one of the commands

[monono]

Great idea! I´m in! Also I never worked on a wiki before.
I am using MrTAToad´s homepage and the online help intesively, because the commands are in a alphabetic list.
Maybe we have to discuss what examples are used per command. Sometimes the examples in the offline help are overwhelming for a beginner. For me it would be nice always to have one minimal and one more complex example.
If MrTAToad would start transfering his stuff, that would be a good start for people to add.

[ampos]

I am one that likes to start with a language reading all the commands, from A to Z, but I encounter very anointing not to find such document.

The chm file seems to be a bit outdated, and to read online, pressing back and forward is a thing I do not like.

...

[Cliff3D]

I am one that likes to start with a language reading all the commands, from A to Z, but I encounter very anointing not to find such document.

The chm file seems to be a bit outdated, and to read online, pressing back and forward is a thing I do not like.

...

You will probably find Mr TAToad's web page (http://glbasic.un-map.com/ - also linked in my sig) to be more your liking for the moment, although if you could add each command to the Wiki as you read it might help embed the command in your memory AND help build the Wiki up to serve us all better in the future!

For my part I've made a very basic start on the reverse type of documentation (starting with a task and explaining how to achieve it, rather than documenting the IDE or the commands like a list of parts) with a "Managing Files" section. There's dummy lines and stuff left out, it's just an example to get feedback before I put too much effort in when I should probably be reading the GLBasic tutorials

Comments, even criticisms, welcome - to help guide me. I would intend, ideally, to use images (screen captures, possibly even .GIF files to animate specific actions) to help illustrate GUI elements, and probably be more in depth about what tab of which GUI element needs to be active.

[okee]

Just an idea, in the help files for each command the details are given
and below every example is a REFS to other commands that are in the same category
i.e.

Code (glbasic) Select Expand

LEFT$()

a$ = LEFT$(text$, count%)
Returns a string that cuts text$ after count% characters from the left.

STDOUT LEFT$("ABCDEFG", 3) // "ABC"

Refs:
MID$(), RIGHT$()


I think it would be more useful to give a small description of the REfs commands i.e.

Code (glbasic) Select Expand

LEFT$()

a$ = LEFT$(text$, count%)
Returns a string that cuts text$ after count% characters from the left.

STDOUT LEFT$("ABCDEFG", 3) // "ABC"

Refs:
MID$()        Extract one or more characters from a string
RIGHT$()      Return characters from the right-hand side of a string

[Cliff3D]

+1