Help file

[cartman2001]

Hi
After very much of effort in thinbasic development i think it's finally time to completely redesign help files.
At the moment this is the weakest element in the thinbasic chain. Good and consistent help can save a lot of
time and frustration to programmers, especialy novices. Which means there will be more of them, which means
the thinbasic community will grow and so on. I think everybody agree with it pretty much.
Thanks again to developers for such a great tool and keeping it free.

br
z

[ErosOlmi]

:oops: I didn't expect a request like that mainly because I've put more effort in thinBasic help than in thinBasic language.
Compared to other programming languages, even commercial, I've always thought thinBasic help was much better.

My open mind attitude tends me to accept all critics but I need more info.
What do you think is necessary to change on help?

Ciao
Eros

[Petr Schreiber]

Hi,

we are trying to do our best to document ThinBASIC as completely as possible. This is why there is updated, context sensitive help file, magazines, articles...
And we are always ready to help. I can see you have just 2 posts at the moment. It is best to ask immediately once you have a problem you cannot solve. We are here to listen.

If you have specific tips on the help files, please post it here, or more appropiately, to ThinBasic Help (http://community.thinbasic.com/index.php?board=13.0) dedicated forum section.
The direct, concrete feedback from the users is very important to us.


Petr

[danbaron]

[font=courier new][size=8pt]I'm surprised, too.

Maybe, cartman is new. At the beginning, everything can seem hard and frustrating.

(I still remember times when I was under pressure to complete programs, and I wanted to kill the environment I was using. But, when you're under too much pressure, my experience is, that you can't find your own mistakes, and you blame the tool.)

:oops:
Dan :x :P

[Michael Clease]

Must admit I was quite shocked when I read cartmans message, I think the help file is one of the best I've found and the fact that anyone can add to it or fix any errors that might be present is a credit to Eros (very open minded).

@Cartman My simple advice is if you dont like it then perhaps you could/should rewrite the help file and I am sure that i'm not the only one waiting to see your version.

Mike

[MikeStefanik]

I suspect that he may be referring to chunks of the documentation that basically just has very little information beyond a simple description, with no remarks, examples or links to related functions. It's most prominent in the "thinBasic Modules" section of the documentation. For example, functions like Console_GetCurrentFontIndex, Console_GetNumberOfMouseButtons, Console_Attach, Console_GetStdHandle, iCrypto_ASCII2String and SMTP_Statistics (which actually has "Enter topic text here" as the description).

They're kind of all over the place, and it's not really consistent how one particular group or subgroup is documented. You have some with really good documentation that clearly explains the function, others where it's little more than just a one-line description of the function, and then others where there's literally just placeholder text. Even with things like equates, you'll have them listed but no description of them (see the "TCP Equates" documentation for an example there). There's also sections where there's really no overall documentation for what that section is about. For example, look at User Interface > UDT predefined in UI module > Bitmap Header Definition where, instead of describing what those UDTs are for, what API's they're used with and so on, it's just a blank page.

Please understand, I'm not trying to be negative or overly critical here, I completely understand how difficult it is to write comprehensive technical documentation. For software that's freely available it's comparatively very good, but there are some gaps there.

Edit: I understand the reflex that some of you are having here to "shoot the messenger", but that's not really going to be helpful to the folks actually writing the documentation. If you look at it with a critical eye, putting on the hat of "technical writer" rather than programmer, there are areas that can be improved. I would agree that it doesn't need to be rewritten from scratch, but there are parts of it that needs work. Telling the guy that he should just rewrite it himself if he doesn't like it is not exactly what I would call useful or constructive. Sometimes some of the best advice you can get is from an "outsider" who is looking at it from a fresh and different perspective, so I'd suggest putting away the torches and pitchforks.

[Michael Clease]

Telling the guy that he should just rewrite it himself if he doesn't like it is not exactly what I would call useful or constructive. Sometimes some of the best advice you can get is from an "outsider" who is looking at it from a fresh and different perspective, so I'd suggest putting away the torches and pitchforks, guys.


:lol:

[ErosOlmi]

:read: yes, I have to admit some areas of the help are very bad :oops:

I have all the summer in front of me to spend some time re-working some parts of help file.
In the meantime is someone have spare time and would like to contribute writing pieces of help he would like to have and/or change, just drop in help forum the text or send me at support at thinbasic.com

Ciao
Eros


PS: post moved into Help forum

[MikeStefanik]

From a project management perspective, before you actually do any work on the help, you might want to go through it all and prioritize the sections, and then the individual topics in those sections. This will allow you to "triage" the help, focusing first on what needs to most work. For example, you could categorize each topic as one of:

1. Complete topic
2. Incomplete links or example code
3. Incomplete description or remarks
4. Placeholder topic
5. Missing topic

In the case of #4, that would be topics that have the topic structure (tables, etc.) but it's missing most or all of the data that should be there. For example, a page that has a list of constants but no descriptions, or a function that has the basic structure (parameters, return value, etc.) but no actual description of what they are.

In the case of #5, that would be topics that are either blank pages, or contain "insert text here" and don't have any actual topic structure or information.

Once all of the sections and topics are categorized, then you'll have a much better overview of where things stand and what needs worked on the most. You could even use those numbers to assign a point value to sections. So, for example, if you had a section with 10 topics, 3 were complete, 2 had incomplete descriptions, 4 had incomplete links and 1 was a placeholder then that section would have a score of 21. The higher the score any particular section has, the more work that needs to be done to complete it.