Manuals rant
TC
Posts: 1,019
Hello all,
First off I would like to apologize if I may upset, or offend anyone. That is not my intention.
What is going on with manuals becoming more and more complicated??? When I started learning how to program in PBASIC with the just released Basic Stamp 2p24, the manuals were well thought out, with very detailed examples. Now it just seams to me that either one, the ones who wright them up assume we can understand something from one sentience. two, that there was a big rush on getting the manual out and things were cut out (I have do it with my job), or three, someone got lazy and decided not to put the effort into it.
I will give a couple examples.
From the Propeller manual, Pg 154;
"If Y started out as 5 then Y // 4 equals 1, meaning the division of 5 by 4 results in a real number whose fractional component equals ¼, or .25."
But when you do the problem with the prop, all you get is 1. Where did the 1/4 or .25 come from, and where did it go? And what am I supposed to do with it?
From the propeller manual, Pg 161;
"X := Y << 2
If Y started out as:
%10000000 01110000 11111111 00110101
...the Bitwise Shift Left operator would shift that value left by two bits, setting X to:
%00000001 11000011 11111100 11010100"
Would of it been hard to show
%10000000 01110000 11111111 00110101
%00000000 11100001 11111110 01101010 <--- shift left 1 place
%00000001 11000011 11111100 11010100 <--- shift left 2 places
That way we can SEE what is happening.
Maybe i'm the only one, or maybe people just deal with it and never really know how it work, the just know it does.
First off I would like to apologize if I may upset, or offend anyone. That is not my intention.
What is going on with manuals becoming more and more complicated??? When I started learning how to program in PBASIC with the just released Basic Stamp 2p24, the manuals were well thought out, with very detailed examples. Now it just seams to me that either one, the ones who wright them up assume we can understand something from one sentience. two, that there was a big rush on getting the manual out and things were cut out (I have do it with my job), or three, someone got lazy and decided not to put the effort into it.
I will give a couple examples.
From the Propeller manual, Pg 154;
"If Y started out as 5 then Y // 4 equals 1, meaning the division of 5 by 4 results in a real number whose fractional component equals ¼, or .25."
But when you do the problem with the prop, all you get is 1. Where did the 1/4 or .25 come from, and where did it go? And what am I supposed to do with it?
From the propeller manual, Pg 161;
"X := Y << 2
If Y started out as:
%10000000 01110000 11111111 00110101
...the Bitwise Shift Left operator would shift that value left by two bits, setting X to:
%00000001 11000011 11111100 11010100"
Would of it been hard to show
%10000000 01110000 11111111 00110101
%00000000 11100001 11111110 01101010 <--- shift left 1 place
%00000001 11000011 11111100 11010100 <--- shift left 2 places
That way we can SEE what is happening.
Maybe i'm the only one, or maybe people just deal with it and never really know how it work, the just know it does.
Comments
While the Propeller Manual v1.20 is an excellent document, it certainly does expect the reader to have more background knowledge. The prime problem has how to keep the text small as an informative primary Propeller reference. Parallax realizes that it isn't addressing the new user's needs and created the LEARN web pages to specifically help out the new users.
And of course, the examples in the Propeller Manual are written in SPIN, so some effort is required to learn how to read the new language. It is indeed different from PBasic. If you want to stay with Basic, there is PropBasic.
Please be patient, both with Parallax and yourself. Microcontrollers and computer programming do require acquiring improvements in learning jargon and reading rather dense language. Your skill will evolve and you will be happy to have the ability. I suppose that somethere Parallax should just say, "While we aim to satify our customers, some thought and learning are required.|
Your example certainly wouldn't be hard to insert. But a complete revision of the Propeller Manual with complete examples (and suggested schematics) would make the book easily twice the size.