1. Good documentation

(It might be not fair to ask, but at least to mention).

Intro:
Long time ago I was programming in MS-QuickBasic. I could use this language since it came with good (let's say amazing) documentation.

Few years ago I was programming in MS-VBA (Visual-Basic for Applications)... The documentation was simply terrible. I was looking for description for specific objects - and that's all I found: a description. There was no example at all. No tip. Nothing. I was moving in circles inside the huge manual, and eventually returned to the same point (subject) after an hour of search.
MS-VBA manual did not supply examples or tips for the most important topics - only description.

In other words MS-VBA (unlike MS-QuickBasic) behaves like this:

for i = 1 to 10 do         -- count from 1 to 10 
   printf(1, "\n%d", i)    -- print the number on the screen on a new line 
end for                    -- return to counter 

The documentation in the above code describes the operation, nothing else.
I found the MS-VBA manual totally useless. again: absolutely useless. misleading. Huge manual with no valuable info - especially on the hot topics. All I could do then is to try to cheat the database-objects by assigning all kinds of experimental SQL strings to them - instead of using the objects properly, etc.

Chapter 1:
See for example the topic arcsin in Euphoria manual:


8.24.3.6 arcsin

include std/math.e
namespace math
public function arcsin(trig_range x)

Return an angle given its sine.

Parameters:
value : an object, each atom in which will be acted upon.

Returns:
An object, the same shape as value. When value is an atom, the result is an atom, an angle whose sine is value.

Errors:
If any atom in value is not in the -1..1 range, it cannot be the sine of a real number, and an error occurs.

Comments:
A value between -PI/2 and +PI/2 (radians) inclusive will be returned.
This function may be applied to an atom or to all elements of a sequence.
arcsin() is not as fast as arctan().

Example 1:

s = arcsin({-1,0,1})
s is {-1.570796327, 0, 1.570796327}

See Also:
arccos, arccos, sin


... I know it's too much to ask, but, an average proud elementary school senior (like me) would appreciate to find:

  1. Practical example(s): some truly useful example of real life use.
  2. Tip(s): I didn't learn trigonometry, so can you give me a hint? cool and valuable info that only the professors in university can think of?

Chapter 2:
arcsin() is just an example, since it is a very useful function if you've learned trigonometry. But many new users would love to see a practical example(s) and tip(s) for, let's say: and_bits(). What can I do with and_bits()? hot Tips where and_bits() can save my life or at least make them better.

This applies to any other topic.

Bibliography:

  1. Microsoft QuickBasic 4.5
  2. Microsoft Visual-Basic for Applications (VBA)
new topic     » topic index » view message » categorize

2. Re: Good documentation

You make some good points.

I frequently find myself writing convoluted code to do something, and all the while having the suspicion that "there must be a better way to do this" - most likely with only one or two lines of code.

When I have taken the time to write an accurate description of the problem, AND posted here, AND someone who has the answer has seen my question and replied, that's what happened - I got a much clearer, cleaner, and probably faster-running, solution.

But that is relying too much on luck. It would be really nice if there were more 'solutions to real-life problems' in the documentation. I could look them up myself!

new topic     » goto parent     » topic index » view message » categorize

3. Re: Good documentation

Shian Lee, I agree that you selected a topic that needs much work.

I have begun a re-write of the arcsin function.

More elaborate (real world) examples belong in a tutorial of some kind. I can come up with lots of examples from physics, navigation, surveying, ... but that would also require an explanation of the technical background behind each example. Bloated tutorial examples do not belong in regular documentation. That just says that I should write a few books.

I downloaded Quick Basic, maybe I'll find the documentation you have mentioned.

The o[4 PDF has about 700 pages. If only I can upgrade one page per day...

_tom


trig_range

include arcsin.e 
public type trig_range(object x) 

values passed to arccos and arcsin must be in the inclusive range [-1,+1]

arcsin

include arcsin.e 
public function arcsin(trig_range x) 

returns an angle in a right triangle given its sine.

Arguments:
  1. trig_range : an atom or a sequence of atomic items; each value is a trig_range ratio.
Returns:

An object, the same shape as trig_range, each atom is an angle measured in radians.

Errors:

The arcsin function requires arguments in the inclusive [ -1..1 ] range; a typecheck error occurs otherwise.

Comments:
 
             /|   
hypotenuse c/ | a opposite  
           /__| 
          A  b adjacent 
      angle 
 
 The right triangle abc 

The arcsin (angle in radians) is the inverse function of the sin (ratio of a/c ) function .

The argument to the arcsin function must be in the inclusive range of -1 to +1 .

The return value is an angle, measured in radians, in the inclussive range of -PI/2 to +PI/2 .

The arcsin may be applied to an atom or to all atomic items in a sequence.

Note:

The arcsin function is not as fast as the arctan function.

Example 1:
s = arcsin({-1,0,1}) 
? s 
--> {-1.570796327, 0, 1.570796327} 
 
include std/mathcon.e 
? PI/2 
--> 1.570796327 
Example 2:

In the right triangle

 
             /|   
hypotenuse 5/ | 4 opposite  
           /__| 
          A  3 adjacent 
      angle 
 
 The right triangle abc 

the sine of A is opposite/hypotenuse. Given the ratio 4/5, what is the angle A in radians?

                                                     include std/math.e 
atom r = arcsin( 4/5 ) 
? r 
--> 0.927295218 
r = rad2deg(r) 
? r 
--> 53.13010235 
See Also:

arccos | arctan | sin | PI | rad2deg | deg2rad

new topic     » goto parent     » topic index » view message » categorize

4. Re: Good documentation

irv said...

I frequently find myself writing convoluted code to do something, and all the while having the suspicion that "there must be a better way to do this" - most likely with only one or two lines of code.

True.

To be honest - I usually look at the example before I read the description.

I remember once, 20 years ago, a guy from University called me and asked for help in calculating a communication checksum. This Russian guy told me that he already tried everything - but he can't figure out what's wrong.
I told him the formula on the phone - it was a single short line.

Same thing happened to me with calculating PID (Proportional-Integral-Derivative) for controllers - you can read 10 books and still don't understand how to do it. But it takes 20 lines of Euphoria code to explain everything.

i.e. from my experience, a short example code can describe the behavior of a function much better then a long description. As much as the function is more complicated - a code example is more helpful.

These days I would not be able to use many Euphoria functions without Wikipedia. I don't think it's right. There must be a short code example attached to the description. A real-life example that I may want to copy/paste to my own program...

new topic     » goto parent     » topic index » view message » categorize

5. Re: Good documentation

_tom said...

trig_range

include arcsin.e 
public type trig_range(object x) 

values passed to arccos and arcsin must be in the inclusive range [-1,+1]

arcsin

include arcsin.e 
public function arcsin(trig_range x) 

returns an angle in a right triangle given its sine.

Arguments:
  1. trig_range : an atom or a sequence of atomic items; each value is a trig_range ratio.
Returns:

An object, the same shape as trig_range, each atom is an angle measured in radians.

Errors:

The arcsin function requires arguments in the inclusive [ -1..1 ] range; a typecheck error occurs otherwise.

Comments:
 
             /|   
hypotenuse c/ | a opposite  
           /__| 
          A  b adjacent 
      angle 
 
 The right triangle abc 

The arcsin (angle in radians) is the inverse function of the sin (ratio of a/c ) function .

The argument to the arcsin function must be in the inclusive range of -1 to +1 .

The return value is an angle, measured in radians, in the inclussive range of -PI/2 to +PI/2 .

The arcsin may be applied to an atom or to all atomic items in a sequence.

Note:

The arcsin function is not as fast as the arctan function.

Example 1:
s = arcsin({-1,0,1}) 
? s 
--> {-1.570796327, 0, 1.570796327} 
 
include std/mathcon.e 
? PI/2 
--> 1.570796327 
Example 2:

In the right triangle

 
             /|   
hypotenuse 5/ | 4 opposite  
           /__| 
          A  3 adjacent 
      angle 
 
 The right triangle abc 

the sine of A is opposite/hypotenuse. Given the ratio 4/5, what is the angle A in radians?

                                                     include std/math.e 
atom r = arcsin( 4/5 ) 
? r 
--> 0.927295218 
r = rad2deg(r) 
? r 
--> 53.13010235 
See Also:

arccos | arctan | sin | PI | rad2deg | deg2rad

That's it! That's what I meant! The basic knowledge. Not more then this!

Till now I cannot use arcsin without Wikipedia...

From your new example and description I can see what arcsin is all about.

Shian.

new topic     » goto parent     » topic index » view message » categorize

6. Re: Good documentation (arc length?)

Special request from Tom or anyone else:

I would like to know the way to calculate the length of an arc. (arc of a circle or ellipse).

There are many ways to do it, but unfortunately the last time I applied to work for NASA I was rejected. I guess that I'm not good enough.

So, what I need is: an accurate, simple, fast, practical, proven way to calculate the length of an arc.

I already found my own way to do it, when I wrote the program for an iron cutting machine. But, obviously there is a better way.

I've tried all those formulas from the Internet - but the most accurate formulas gave me really strange results that I could not understand (it might be good for flying to the moon, but not really what I needed). Other formulas gave me not accurate results.

The cutting machine has to move exactly between each 0.1mm points of an arc, so I needed a good formula for this.

The best thing that could happen is if an accurate formula was included as a code example for sin() or cos() - since it's a very useful task, but seems to be an impossible mission.

I hope that I don't talk nonsense here.

Thank you.

ps: I forgot to mention that important part of the MS-QuickBasic documentation was a directory of valuable example-programs.

EDIT: BTW, I was looking now in Wikipedia, it seems that lots of new articles were written since the time that I was looking for Arc-Length. Yet, I'm still wondering if those new(?) formulas are accurate enough.

new topic     » goto parent     » topic index » view message » categorize

7. Re: Good documentation (MS-VBA Vs. Access2Base)

Hi Tom,

A clear example for good documentation is the MS-VBAL (Microsoft VBA Programming Language Documentation) Versus Access2Base on-line help (for learning how to program in OOP for MS-Access Versus LibreOffice Base).

  1. The Access2Base was written by a person, Versus MS-VBAL that was written by Microsoft corporation.
  2. The Access2Base manual was written for the users, Versus MS-VBAL manual that was written as a technical reference for the developers themselves.
  3. The Access2Base manual is short, with lots of examples and tutorials, Versus MS-VBAL manual that is a long technical manual, with no examples, tutorials, kindness.
  4. The Access2Base manual assumes no other documentation, Versus MS-VBAL manual that assumes that there are many kind books in amazon to help the user get started.



The ridiculous thing is that you actually read the Access2Base manual to understand how to do simple things in MS-Access.

It also shows again and again how OOP (Object Oriented Programming) is a friendly programming technique for the Pentium CPU - but not for the human brain. In My Humble Opinion.

new topic     » goto parent     » topic index » view message » categorize

8. Re: Good documentation (MS-VBA Vs. Access2Base)

Thanks for showing me Access2Base documentation.

There are some good ideas there. I will spend some time to see how their presentation could be adapted to Euphoria documentation.

_tom

new topic     » goto parent     » topic index » view message » categorize

9. Re: Good documentation (MS-VBA Vs. Access2Base)

Thank you Tom,

As it says in Access2Base site: "It's about converting PEOPLE, not data".

Euphoria is A-L-R-E-A-D-Y supreme in converting data. But a total disaster in converting PEOPLE...

One of the main reasons for this is: A truly terrible strategy - by truly talented people.

IMHO

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu