Idea for tutorials

[marcuslee]

I've attached my beginning idea for restructuring the tutorials that come up with the startup application in thinAir. I have added a page describing the use of the InputBox. I think it fits well right after the information on Variables.

In the long run, though, I wonder if grouping tutorials by topic is such a good idea. One of the next things that I think would work well right after InputBoxes is an article on expressions. There may be enough for an entire tutorial or just a page. I'm wondering if grouping all beginner subjects in the same beginner tutorial would make learning the language quicker. I think so. I was wondering what everyone else thought. That's why I didn't just submit my idea to Eros only.

So, what I have attached is just a start, because in the end, the beginner tutorial wouldn't just be about Variables ... that's just where it would start. Then, the tutorial would go through several concepts that don't require other modules ... the basics of programming, in other words. Then, we could have other tutorials that go into more detail on the modules such as the console and GUI versions that have already been started.

If what I have described here doesn't make sense, I would be happy to work further on altering the current format to demonstrate what I am trying to get across.

Of all the BASICS out there that I have tried, I think I like thinBasic the best. It is free (donations are welcome, of course). Help from experts is easy to get. It does more than the other good BASICS out there, methinks. I don't think it is overreaching to say that thinBasic could be the leader in the BASIC category if it were completely accesible to brand new people who know little of programming. But, a step-by-step tutorial is what is missing.

Okay, I'll get off my soap box for a little while.



Mark

[ErosOlmi]

Mark,

thanks a lot for working on this matter.
It is of great help for me reading what you think about thinBasic. There are many many good programming languages out there. I think thinBasic can make its part in helping programmers (expert or newbie) in some specific areas or programming just for fun.

See what we get, than I will add your material to thinTutorial.

Ciao
Eros

PS: I'm moved your post into tutorial forum.

[Michael Hartlef]

Marc,

yes, thinBasic is awesome. To bad it doesn't run on OSX natively but someone can dream or? :) And thinBasic is huge, that is why it is difficult to create the things you mentioned. The best way I think is to just go ahead a create something that Eros can link into the tutorial. Eros simply can't do everything alone and has his hands full already. Sometimes I wonder if he clones himself for certain tasks. :)

I say just go for it.

[Petr Schreiber]

Mark,

good job!
Any help from your side is welcome, and your plans for tutorial sound very good!


Petr

[marcuslee]

Any help from your side is welcome, and your plans for tutorial sound very good!



I wonder if you will still say that after the next round of changes. I've been working on the format a little more. And, I even altered the script file a little. The reason for altering the format even more in my mind is to make it easier for people new to the language and easier for ones submitting articles in the future.

The way y'all had it set up before would make it a little cumbersome in my mind to navigate the tutorials. So, one change I made was to put all the lessons of a certain tutorial in one folder. So, you don't have tons of tutorials but tons of lessons in one tutorial. In other words, there is not a tutorial on Variables but several lessons within the "Beginning" tutorial that cover variables. I hope my changes make sense.

I changed "Startup" tutorial to "Beginning" tutorial, which makes more sense in English, IMHO.

Since I changed the folder layout, I took out the "author" section of the header since multiple authors may contribute to the same tutorial, each writing a different lesson. We can find another place to mention the authors, if you wish. I personally don't need recognition for any articles that I write. This is the least that I can do to help the cause. Wish I had money to give. Maybe in the future. But, we are moving because we don't have much money. Well, that's one of the reasons anyway.

In the header section I also took out the Version Number. That doesn't make much sense to me. Yes, with thinBasic and thinAir, but not with the tutorials.

I also moved the INDEX file to the first lesson, combining information where I needed to. I hope everyone likes the new format. I think all of these changes can make the tutorials easy to expand on.

One other semi major change I want to work on soon is smoothing out English syntax throughout the application and HTML pages, which I think will go a long way to making thinBasic even more accessible.


Mark

P.S. - Please comment if you can. I would love some input. Am I making good changes? I don't want my time wasted.

EDIT: To avoid confusion for everyone, me included, I have taken off the attachment on this post. An up-to-date version can be downloaded elsewhere.

[Petr Schreiber]

Hi Mark,

I like it. Only thing I would consider, if you don't like versioning, use date of last change to the tutorial.
Imagine you publish tutorial, and in 2 months you update it with new stuff because ThinBASIC introduces some cool commands.

From first look on the tutorial, it might seem nothing changed, but the date could be good indicator for "check it out, its updated". Nobody will check file time, but when you see 22-Nov-2009 you can clearly see it is something new.

English smoothing is welcomed too. I am not native speaker so my English can appear robotic or disturbing to the eye of the reader. Making the text "perfect English" will make the tutorials more accessible as you say.

Regarding author(s) - the good thing was that you saw who wrote it, so you could directly ask him(them) in case of trouble.


Thanks!,
Petr

[Michael Hartlef]

Nothing to add to Petr's comments.

[marcuslee]

Only thing I would consider, if you don't like versioning, use date of last change to the tutorial.
Imagine you publish tutorial, and in 2 months you update it with new stuff because ThinBASIC introduces some cool commands.

From first look on the tutorial, it might seem nothing changed, but the date could be good indicator for "check it out, its updated". Nobody will check file time, but when you see 22-Nov-2009 you can clearly see it is something new.


You hit the nail on the head, really. A modification date makes more sense for articles that are being put up at random or at uneven intervals. Perhaps in the future if there is enough interest, a forum thread or email newsletter can go out, telling people about new additions to the tutorial. If anyone would like to help out in an endeavor such as this, I would be happy to help out where I can.



English smoothing is welcomed too. I am not native speaker so my English can appear robotic or disturbing to the eye of the reader. Making the text "perfect English" will make the tutorials more accessible as you say.


I am always nervous about mentioning that because I don't want to offend anyone. I don't want it to come off like I don't have respect for all of you (non-native English). Cause the opposite is true. Especially Eros but a lot of the others as well ... y'all have accomplished so much. And, I am honored to be a part of this. And, even though I get busy with life and don't do much with programming from time to time, I always come back. With the tutorial application accessible to me, maybe I'll stick around a little longer this time. Moving to Kansas means I am not going to be working for myself anymore, so maybe I will have more time for thinBasic. We'll see!



Regarding author(s) - the good thing was that you saw who wrote it, so you could directly ask him(them) in case of trouble.


That's a good point. It depends on what we decide to do with the modification date. We could put the modification date and the contributing author at the top of a lesson (article). Should there be a modification date for each article or for the whole thing all together? If there is going to be just one date change, then the contributing author could be posted at the end of a lesson. There is a date posted in the INI file. That could simply be shown in the header where the Version was previously shown. I'll look into that and see if I can figure it out. It is always hard for me to alter someone else's program ... I'm slow to understand where things are.

If I am taking an active role in the tutorials, I will be able to recognize my on writing style. So, knowing an author would only be helpful to me if it isn't me doing the writing. And, here's some blunt honesty ... at present, I don't see many of y'all contributing to this project because y'all are so busy with other thinBasic projects as well as real life duties. And, I wouldn't ask for any futher help besides helping me with the parts of thinBasic and programming in general that I don't completely understand.

Well, this is exciting! Let's see where it goes.




Mark

[Michael Hartlef]

I vote for author and date.

[marcuslee]

I vote for author and date.


I'm cool with that. Should the author and date be at the top or bottom of the article?

I'ved attached the next update to the tutorial. I was able to add the modification date in the header. I don't completely understand all the commands used to get it there, but I can alter other people's code to get it done.

There are a couple more lessons in the tutorial. The "Conditions" lesson isn't complete, though.

EDIT: The attachment has been removed. An up to date Tutorial.zip can be downloaded elsewhere.

Mark

[Petr Schreiber]

Very good,

keep it up!

Maybe for expressions I would add that:


x = x + y

can be written as


x += y


... and so on. I find this very elegant.
Please see "Assignment operators" topic in the help.

[ErosOlmi]

Wish I had money to give. Maybe in the future. But, we are moving because we don't have much money. Well, that's one of the reasons anyway.


Mark,

we do not need money. Of course they are welcomed and will help to pay thinBasic web bills (we are on a dedicated physical server).

The fact you are still with us, the fact you are making a great job, the fact you are helping us to create better, updated and more professional material, the fact you are spending your time (and time is so precious) here ... well, all this really pays and says it all.

So, to me you are making a great job for which I can only say a big thanks. Your tutorial will be present in next thinBasic release.
Never forgot real life (your family, your job, your friends, ...) must always have higher priority but you already know that.

Ciao and thanks again
Eros

[marcuslee]

Maybe for expressions I would add that:


x = x + y

can be written as


x += y


... and so on. I find this very elegant.



With some of these basic topics, there is a lot that can be said, a lot that can be covered. I haven't decided if I want to write short articles, thus having an Advanced Expression article later on or write longer articles that cover more material.

I wouldn't really consider your suggestion advanced, but it isn't the most basic either. What do you think?


Mark

[Michael Hartlef]

For an experienced developer




x += y


is more elegant, but I think for a beginner it could be confusing at first.

[marcuslee]

The fact you are still with us, the fact you are making a great job, the fact you are helping us to create better, updated and more professional material, the fact you are spending your time (and time is so precious) here ... well, all this really pays and says it all.


I appreciate that!



So, to me you are making a great job for which I can only say a big thanks. Your tutorial will be present in next thinBasic release.
Never forgot real life (your family, your job, your friends, ...) must always have higher priority but you already know that.


I do what I can. Do you have any idea when the next release is going to be? I don't want any articles I've added to be kind of half done if the release is going to be soon. If there isn't any idea about when it might be or if it is a little far off, I'll continue as I have done so far.

As regards the Modification Date and Authors, I'm guessing that this needs to be done on an article by article basis. If that's the case, do I need to have the date in the header as it is in the most recent update? Or, does this need to be manually put in with each article? If we only have the one date at the top, do we need to specify somehow which articles are new?

I made some fairly significant changes to the format because I thought it would be easier to organize, but I am not sure what to do about authors and modification dates. Personally, I am happy with one date at the top of the tutorial, and as far as authors go, I don't really care if my name appears anywhere. I am happy to go with the consensus. If someone else wants to submit something, their name can appear on the article if they wish.

However, I see the need to know what is new material and what has always been there. I'm not sure how to accomplish that with the changes I have made. Suggestions are welcome, of course.


Mark

[marcuslee]

For an experienced developer




x += y


is more elegant, but I think for a beginner it could be confusing at first.



Yeah, that was my thinking. There is much I didn't put into the article about expressions. There's plenty for another go around later.

I've attached another update. I will be deleting the previous one right after posting this. Should I continue to update the way I have been? Or should I have a place to always keep the most recent update, maybe the top of a new topic?

Personally, I don't want to add more on to Eros, so I don't really want to just submit it to him through email as he initially requested ... though I will do as he tells me. I like the feedback I get from others, suggesting to add something or whatever. Y'all might even catch some of my mistakes.

EDIT: The changes to this version are mostly around the articles I have written. The "Conditions" article is basically complete. The "Input & Output" article has a new label on the side and a section covering MsgBox and Alert have been added, though part of that may have been in the last update. I'm not sure since I'm not really good at documenting changes. My hats off to Eros!

Mark

[Michael Hartlef]

Yes, have the new version always attached to the very first post.

[marcuslee]

Yes, have the new version always attached to the very first post.


Well, the next time I update, I will probably start a new topic for my unofficial updates.


Mark

[ErosOlmi]

Do you have any idea when the next release is going to be? I don't want any articles I've added to be kind of half done if the release is going to be soon. If there isn't any idea about when it might be or if it is a little far off, I'll continue as I have done so far.


We are in Beta phase of version 1.7.10 so even if some article is unfinished I think it is OK.
Expect a new beta every week or so. I will release a new one in 2/3 days depending when I will finish current changes.
Definitive final version by mid of Dec.

As already said, the best is to have only one version of tutorial in one single place.
Choose a forum where to work, make a new post and update tutorial file always in first post of that thread.

Ciao
Eros

[marcuslee]

We are in Beta phase of version 1.7.10 so even if some article is unfinished I think it is OK.
Expect a new beta every week or so. I will release a new one in 2/3 days depending when I will finish current changes.
Definitive final version by mid of Dec.


How you do that is beyond me!! Work a real job and accomplish so much with thinBasic. You are a god among men! :escribe:

That gives me a time table to work with. I would like to be able to get the tutorial to a certain spot. We'll see. But, it seems that it doesn't matter. If I miss it, the next beta comes knocking on the door. I don't think I have ever seen any other program updated as much. :eusaclap:



As already said, the best is to have only one version of tutorial in one single place.
Choose a forum where to work, make a new post and update tutorial file always in first post of that thread.


Yeah, I kinda knew that even when I was asking. Sometimes I just like talking for talking sake. I'll work on that!



Mark

[ErosOlmi]

I don't think I have ever seen any other program updated as much. :eusaclap:


Well, some people do not like it because they use the equation: "many updates" = "many bugs". This can be true but it cannot be considered "the rule".
Many updates also mean (at least here in thinBasic) some new features, sometimes even important and in general suggested by programmers using thinBasic.

As a programmer, I've always loved programmers tool updated very frequently. I like to have fixes to bugs very quickly released and I like to be able to take advantage of new features.
I see many people here are with my idea so we will continue on this "frequent update" line.

Ciao
Eros