▼
Posts: 528
Threads: 40
Joined: Dec 2008
I flashed a 20b to a 34S last night and I'm really enjoying it. When my 30b arrives from Eric, I'll apply the keyboard overlay and flash that one too.
I'm running version 2.11630 (as shown by the VERS command) and I have two suggestions.
First, when I press any key, the RPN annunciator flashes off and then back on. It would be nice if it stayed on.
Second is a usability thing for new users. I was playing around with it last night without the manual and I accidentally got into integer mode. It took me a good 10 minutes to figure how to get out of integer mode - I eventually stumbled onto H.d to do it. This was rather frustrating and I think for a new user it would be really annoying. So my suggestion is to change FIX, SCI, and ENG to change the calculator back to real mode if it's in integer mode. Even new users will probably know how to change the display using these functions and if you change the display mode, you probably want to start using real mode anyway.
Congratulations to everyone who put this together. It's a wonderful accomplishment.
▼
Posts: 4,587
Threads: 105
Joined: Jul 2005
Quote:
I'm running version 2.11630 (as shown by the VERS command) ...
Can't be true. Must be 2.1 1630.
Quote:
First, when I press any key, the RPN annunciator flashes off and then back on. It would be nice if it stayed on.
This is by purpose and was meant to give at least some value to that annunciator. We're in RPN always, so it's only not lit as long as the WP 34S is busy.
Quote:
Second is a usability thing for new users. I was playing around with it last night without the manual and I accidentally got into integer mode. It took me a good 10 minutes to figure how to get out of integer mode - I eventually stumbled onto H.d to do it. This was rather frustrating and I think for a new user it would be really annoying.
How about RTFM? Your experience is nothing more than the just deserts for not doing it ;-)
Quote: Congratulations to everyone who put this together. It's a wonderful accomplishment.
Thank you :-)
Walter
▼
Posts: 372
Threads: 42
Joined: Mar 2011
Quote: This is by purpose and was meant to give at least some value to that annunciator. We're in RPN always, so it's only not lit as long as the WP 34S is busy.
What about reversing it (i.e. only light it when the calc is busy)? That would declutter the display a bit...
Re. how to exit integer mode, now of course it is instinctive to me after many months, but I remember the first time I used the 34s I had the very same problem - at last I resorted to resetting the calc. I don't remember right now if the manual is clear on how to enter/exit integer mode, but I remember that at the time it wasn't... I also suggested changing the key label to say "real" or something like that, but apparently that's exactly what ".d" means! :)
Cristian
▼
Posts: 3,229
Threads: 42
Joined: Jul 2006
Quote: What about reversing it (i.e. only light it when the calc is busy)? That would declutter the display a bit...
I like this suggestion :-)
- Pauli
▼
Posts: 653
Threads: 26
Joined: Aug 2010
While you're at it: maybe we could even get rid of that awkward "running Pro6rAM" display. ;-)
Dieter
Posts: 3,283
Threads: 104
Joined: Jul 2005
Doesn't work Pauli: The RPN annunciator is only lit when the calc accepts RPN input. It's turned off for temporary displays (such as VIEW) to indicate it is safe to press <- without disturbing X.
So RPN does what is says: You can enter RPN data and commands.
▼
Posts: 3,229
Threads: 42
Joined: Jul 2006
Drats. This device is too complex to fully understand anymore :-(
- Pauli
▼
Posts: 225
Threads: 9
Joined: Jul 2008
Well if it is too complicated for you, Pauli, the rest of us are in real trouble :)
By the way, I am enjoying the WP34S way to much. Thank you Pauli, Walter and Marcus!
Posts: 1,619
Threads: 147
Joined: May 2006
Quote:
Doesn't work Pauli: The RPN annunciator is only lit when the calc accepts RPN input. It's turned off for temporary displays (such as VIEW) to indicate it is safe to press <- without disturbing X.
Thank you for this. This is very handy. I used this today on a plane while debugging code. Now if you can find a way to VIEW ALL and have X-T scroll by, that'd be nice. :-)
Posts: 528
Threads: 40
Joined: Dec 2008
Quote:
How about RTFM? Your experience is nothing more than the just deserts for not doing it ;-)
The "R" part (read) is easy and I did read it. It's the other "R" (remember) that was the problem.... :) I didn't have the manual handy at the time. By the way, the manual on page 22 shows the command as "[.d]" while the keyboard graphic shows it as "[H .d]"
Obviously the functionality is there. My only point is that finding it isn't intuitive and I offered a possible change that would, IMHO, be more intuitive. Usability matters. I haven't looked at the code yet so I don't know if this would be hard to implement, or if there are reasons why it shouldn't work as I suggest.
Dave
▼
Posts: 3,229
Threads: 42
Joined: Jul 2006
Quote: I haven't looked at the code yet so I don't know if this would be hard to implement, or if there are reasons why it shouldn't work as I suggest.
It wouldn't be at all difficult to implement. The function for ALL, FIX, SCI, ENG and DISP is:
void cmddisp(unsigned int arg, enum rarg op) {
UState.dispdigs = arg;
if (op != RARG_DISP)
UState.dispmode = (op - RARG_STD) + MODE_STD;
UState.fract = 0;
}
Replacing the UState.fract = 0; line with op_float(NULL, NULL, OP_FLOAT); will do the mode switch and convert the stack properly. Had you considered this being required?
As always, there are other issues to consider:
- Do all these five commands need to switch out of integer mode? Should they?
- Is making these functions have such a side effect a good thing or not? Simple functions are almost universally better than double barreled ones.
- What other side effects will happen here? One I know of is that H.MS display will be lost.
Changes like this usually have subtle side effects which aren't obvious.
- Pauli
Posts: 1,545
Threads: 168
Joined: Jul 2005
<rant on>
One could always suggest writing a manual that even advanced users don't find cryptic. The manual as-is might contain the information, but then again, an SD card might contain a lot of information but is not easily accessible unless you have an SD card reader.
C'mon Walter - there are probably 10-20 basic things that could be added to a "Common Questions" section at the end that would be helpful. We're talking about people who have written programs for HP calculators for 20+ years not being able to find fairly basic things in the documentation.
Jake and I are really toying with doing a new, readable manual that doesn't assume an advanced CS degree... but I would ask your forbearance with those who can't find things in your reference manual - which is what it is and will remain given the level at which it is written.
If we do, I will predict our readable manual will be used a great deal more often than the one that exists now - because we won't assume that section 4, paragraph 3, line 6, fifth word is a sufficient explanation of where an important piece of information resides.
My 2 cents, but RTM is getting to be a tiresome response when the overwhelming majority of people here and at HHC find it much too difficult to find basic things in said manual.
</rant off>
▼
Posts: 653
Threads: 26
Joined: Aug 2010
One of the beauties of the German language is its ability to express subtle differences with a vast number of expressions to choose from. This is also true for the English word "manual". Among many others, two possible options here are "Gebrauchsanweisung" and "Benutzerhandbuch". The first one contains the word "Anweisung" (order, command), so here the idea is to tell the user how to use the device: press this button, get that result. On the other hand, the second term means something more like "user's guide" - a handbook that is intended to be a helpful companion to the user, making him familiar with the machine so that he will be able so solve his everyday problems.
I think the current version of the manual is a tiny bit more on the "Gebrauchsanweisung" side, while your idea sounds more like a "Benutzerhandbuch". ;-)
Sooner or later I am sure there will be something that comes closer to your idea of a manual. And since this forum is full of native speakers of many different languages, there even is a chance there will be decent non-English versions as well. ;-)
Dieter
Posts: 4,587
Threads: 105
Joined: Jul 2005
Hmmh, we are talking about modes, aren't we? There's a chapter called "Display and Modes" in said manual. Sounds promising, doesn't it? On its very first page (22), in the very first table, is exactly the information you were looking for. Easy IMHO. YMMV.
▼
Posts: 112
Threads: 9
Joined: Jan 2011
Quote:
Hmmh, we are talking about modes, aren't we? There's a chapter called "Display and Modes" in said manual. Sounds promising, doesn't it? On its very first page (22), in the very first table, is exactly the information you were looking for. Easy IMHO. YMMV.
Asking an innocent question here.
Since you mention Page 22, my English as a First Language tells me that the description of "Cleared by..." does indicate that [FIX], [SCI], [ENG], [H.MS], TIME, and [->][H.MS} will set DECM. That description indicates that the OP's observation/wish is actually how the 'manual' indicates the WP-34S will behave. In practice, however, the WP-34S does not behave like this.
If I have misunderstood, I apologize. I did read the manual.
Posts: 1,619
Threads: 147
Joined: May 2006
Walter,
You are missing an opportunity here. Instead of "RTFM" or "read page ##", how about asking yourself "why?" some struggle with and without the docs? And perhaps use that feedback to improve the documentation so that we can cultivate a larger and stronger community. Perhaps we just need a QR card. You're never going to escape excited users that skip through the ~100 page manual.
The more I use the 34S the more I wish someone would make it. I travel frequently (sometimes weekly) and I never carry a calculator anymore because of space and weight, so I suffer with emulation on my iPhone. Well that changed on this trip. When I packed my bags this morning I took my 34S. I want others to have the same great experience I have had and to feel the same way.
My $0.02US (I'd give you Euros if I had them):
".d" is neither clever nor obvious. On the 16C it's "FLOAT". Given the lack of space "FP" may have worked too.
I had the exact same problem as the OP. Since I could understand all the other symbols, ".d" did occur to me as a possible way to return back to FLOAT, however the leading "H" lead me to believe that it was the inverse of H.MS, and so it is.
That all said. The documentation is awesome, and the fact that we have any quality documentation is largely or solely due to your effort, and I thank you for that. And yes, if you RTFM (Read The Fine Manual) you will find all your answers, except "why?" :-) Please keep up the great work.
Thank you.
P.S. I know that writing docs sucks, and I'd wager that you spend more time on docs than the sum of all the coding time. Your efforts are appreciated. Thanks again.
Edited: 29 Sept 2011, 8:47 p.m.
Posts: 429
Threads: 31
Joined: Jul 2011
Yes, the info is there but I also had the very same problem with finding it the first time I needed it.
Posts: 82
Threads: 8
Joined: Nov 2009
Quote:
(snip)
C'mon Walter - there are probably 10-20 basic things that could be added to a "Common Questions" section at the end that would be helpful. We're talking about people who have written programs for HP calculators for 20+ years not being able to find fairly basic things in the documentation.
Jake and I are really toying with doing a new, readable manual that doesn't assume an advanced CS degree... but I would ask your forbearance with those who can't find things in your reference manual - which is what it is and will remain given the level at which it is written.
If we do, I will predict our readable manual will be used a great deal more often than the one that exists now - because we won't assume that section 4, paragraph 3, line 6, fifth word is a sufficient explanation of where an important piece of information resides.
Right on! Users don't need their hands held, but something beyond the terse descriptions is much needed, not to mention examples and as you suggest a FAQ.
You don't see open source software documentation held closely to the vest, and considering how much you and others are willing to pitch in and help, I suggest that it is in everyone's best interests, including the software team especially, to make the documentation produced up to now available in whatever format is requested, not just as PDFs. To do anything else is, in my opinion, selfish, unproductive, and uncooperative. Further, in the absence of said documentation being made available I am confident the user community, namely those contributing to the project, will find a way to accomplish their objectives.
Quote:
My 2 cents, but RTM is getting to be a tiresome response when the overwhelming majority of people here and at HHC find it much too difficult to find basic things in said manual.
It wasn't just RTM, it was RTFM, which in this forum where people are hopefully trying to help each other I find unacceptable.
Posts: 553
Threads: 57
Joined: Sep 2006
Here, here!
I remember when I was working for the Red Cross as a disaster services officer, teaching Shelter Management. One of the questions on the final test was:
"Your shelter has been in operation fairly well for a few days now. The kitchen staff report some food stuffs missing each night. You watch and find two kids taking food out of the refrigerator in the middle of the night and eating it before going to bed. What is your response and what should you do?"
Almost always, the first answer is "punish the offenders". The proper answer is "ask if the problem is that they are unable to get enough food during mealtimes, and if so, increase the amount of food each person can get".
I don't want to start any debate on shelter management, but the point should be obvious: if a lot of people are complaining about something, there's probably a good chance there is a legitimate reason for it.
In more simple terms, if it walks like a duck, quacks like a duck and looks like a duck, then it's probably a duck.
I heard a lot of comments at the HHC conference that people LOVED the calculator, but the manual was daunting, oppressive, complex, confused and other words. To me, that shouts out for help.
Gene, if you and Jake embark on a better manual, I think you will have a LOT of positive support and comments from the user base. I whole heartedly support it.
My $0.02 anyhow. :-)
thanks,
Bruce
▼
Posts: 4,587
Threads: 105
Joined: Jul 2005
Quote:
Here, here!
Again :-/ Are you sure you meant what you wrote here?
Anyway, you're right with your example. Though I wasn't up to "punish" anybody - I just sometimes wonder. And then I remember what a former senior colleague told me years ago (for the US: no offense intended, the following sentence is a literal translation of this person's advise, but please continue reading thereafter):
"If you write a manual every idiot could use, only an idiot will use it."
(For the US again: No, I know this characterisation doesn't apply to anybody here, of course. The quoted sentence is just indicating a trend, and it's another nice example of the German way of telling the truth directly without a lot of flowers and pampering around - and politically incorrect for sure. Please also note, here you don't see "Objects in this mirror appear smaller than they really are" etched in side mirrors of cars, nor "May contain hot beverages" printed on paper cups, nor anything alike. When we read such stuff, we shake our heads and wonder about foreign habits, education, and everything. BTW, this whole paragraph could be omitted in a German forum :-) just to give you an idea of the easy communication here.)
That said, I am aware of the challenge of writing a manual for people with different cultural background. And "H .d" has a longer history than you can know - but you don't have to, it's my job to guide you to the right keys. Just compare the manual editions 1.12 and 2.1, and I'm confident you see a positive trend.
Anyway,I'll think about a better way to get the DECM message transmitted.
O dear, this post got longer than thought. But I hope it helps a little bit.
Walter
▼
Posts: 553
Threads: 57
Joined: Sep 2006
Quote:
Again :-/ Are you sure you meant what you wrote here?
Autocorrect. ;-) I blame that, and lack of sleep ;-)
thanks,
bruce
Posts: 3,229
Threads: 42
Joined: Jul 2006
Just put a line at the top of the first page of the manual:
To return to floating point mode, select H.d
:-)
Instead, please commit the word version of the manual to our subversion repository and Gene and Jake can get to work on an introductory guide and some learning modules which will usefully augment the current reference manual.
- Pauli
Edited: 30 Sept 2011, 1:49 a.m.
▼
Posts: 4,587
Threads: 105
Joined: Jul 2005
:-) Changed the front page. Hope this helps though I didn't print it bold faced nor underscored :-/
Edited: 30 Sept 2011, 2:29 a.m.
▼
Posts: 3,229
Threads: 42
Joined: Jul 2006
But did you keep the italic????
:-D
- Pauli
▼
Posts: 4,587
Threads: 105
Joined: Jul 2005
Ooops, not really. Severe drawback! Hope it will be read nevertheless ;-)
▼
Posts: 3,283
Threads: 104
Joined: Jul 2005
Walter, I asked Gene about his offer to write a Beginner's Guide and he told me he will only start off with your original document (fonts and all included) in his possession. Pauli has kindly asked you to put the information onto the SVN repository and I wholeheartedly second this proposal. Make the documentation a community effort, too!
▼
Posts: 82
Threads: 8
Joined: Nov 2009
Quote:
Walter, I asked Gene about his offer to write a Beginner's Guide and he told me he will only start off with your original document (fonts and all included) in his possession. Pauli has kindly asked you to put the information onto the SVN repository and I wholeheartedly second this proposal. Make the documentation a community effort, too!
I could not agree more with this. Everyone will benefit. Everyone will have fun. More time for other things! THANK YOU, Marcus! And THANK YOU in advance, Walter!
Edited: 30 Sept 2011, 9:27 a.m.
Posts: 1,619
Threads: 147
Joined: May 2006
Quote:
Make the documentation a community effort, too!
While I agree in principal, in practice this can be difficult, especially when using Word. I've had nothing but problems with collaborative Word projects. XML vs compat mode docs, markup, and merge do not work as cleanly as one would like. I've lost so much time due to Word bugs that I now hand merge in changes.
If new works are going to be generated from Walters work that is one thing, but if others are going to contribute to Walters document then some standards need to be set in place first, and I'd expect Walter to be spending a lot of time proofreading and not documenting.
sf.net supports Wikis. If there is going to be a community documentation project that may be a good place to start. All changes are tracked. Wikis do not generate very good printed documentation however. But that can be addresses after this project stabilizes.
▼
Posts: 4,587
Threads: 105
Joined: Jul 2005
Egan,
Quote:
I've had nothing but problems with collaborative Word projects. XML vs compat mode docs, markup, and merge do not work as cleanly as one would like. I've lost so much time due to Word bugs that I now hand merge in changes.
What you describe is exactly what I experienced also for many years in my professional life. Documents and structures, carefully assembled by few, then corrupted by (usually some more) people of good will but no clue - having fun, as Brian wrote. I'm not very keen on mending such a mess again.
Way back in April, there was a prominent member of this forum asking for my manual data file. He claimed he was planning some nice extensions of it. I offered him he may write whatever he thinks being appropriate straight ahead, send it to me, we'd discuss it and I'd insert it in the manual at a location we agree on, in a decently formatted way. No, that wasn't the way he wanted. He kept asking for data, and I eventually sent him my entire WORD file. Apparently then he or his mailbox wasn't prepared for it - I found out several weeks later by asking myself - I sent it again - then he complained these were old data etc. etc. Making a long story short, I never got back a single byte from there so far.
Despite this very frustrating experience, I am willing to offer such a collaboration once more. But please, don't you cry you want to have all and want it now. One basis of our WP 34S project turning out successfully is both of us, Pauli and me, have a common vision, we committed and delivered, each of us in his area of expertise, and we discussed the open points until we both could agree. We needed some time sometimes, and we also had some hard discussions, but I never felt our business lost balance, it was always a give and take. We then integrated two more people, and each of them brought his area of expertise which wasn't covered sufficiently in our team before.
The manual was published quite early, together with the invitation for constructive critics, as you find in the archives. And IIRC, we've listened to almost every reasonable proposal and remark and took them into account. So it went pretty well, though the amount of active "beta reader" turned out being a bit less than I expected.
After all, now we've got a product, and I get the feeling all kind of folks are trying to hopp on the bandwagon now. Come on, contribute something useful yourself if you want to join late. All the tools and information are readily available. But don't claim you *will* do something, provided you get 100 pages for free first.
Personally, I'm not ready yet to sacrifice our work achieved so far to the cro..., hmmmh, community. I see this opinion is not popular, maybe out of time, but that's the way I think it's right - and that's how we reached this result. If you can't stand that, feel free to start your own project. I wish you good luck, may offer some support if you like and am looking forward to *your* results.
Ok, so now I will be grilled for that :-(
▼
Posts: 3,283
Threads: 104
Joined: Jul 2005
Not grilled, just asked over and over again.
Putting up your work and its support files on SF would have the added benefit of creating a safe backup of the files. And authors of additional documentation would have a much better start, regarding formatting and style.
Posts: 228
Threads: 7
Joined: Aug 2011
No grilling from me. Been there, done that.
I like the current reference manual the way it is.
I do think a separate, distinct, user guide would be nice. Everything is in the current manual, somewhere, just for us regular dummies it takes a bit more effort than we're used to, to find it and understand it.
We're all used to HP manuals which pretty much spell it out for you with nice pretty "button" icons along the left and explanation down the left.
I'm a big fan of wikis - my past and present employers have used these successfully for "HowTo" type stuff. There are many wiki engines, some better than others:
[ul]
wiki4hp.com (DokuWiki) is on the primitive side.
Twiki is better and
Confluence ($$) has pretty good wiki to document publishing.
MediaWiki (wikipedia) is also free and has a "create a book" thing.
SourceForge Wiki - haven't looked at it.
Ultimately someone or a small group of editors has to keep stuff consistent, not only an army of contributors.
Want me to look at the sourceforge wiki?
▼
Posts: 225
Threads: 9
Joined: Jul 2008
Quote:
I do think a separate, distinct, user guide would be nice.
I would like to donate my time helping to write a WP34S User's Handbook that is written in the same style as the HP-25, HP-41C, HP-15C, HP-42S Handbooks. I think a printed copy would provide the finishing touch to make the "WP34s Package" a complete product that could be sold to anyone.
▼
Posts: 228
Threads: 7
Joined: Aug 2011
There, I think I have finished the WP-34s Users' Guide
:-)
okay, but it's a good start :-)
▼
Posts: 528
Threads: 40
Joined: Dec 2008
Now THAT'S funny!!! Thanks for making me laugh.
Posts: 225
Threads: 9
Joined: Jul 2008
Well... Yes. Yes, that is a great start but I think we need to... add just a bit more. I think with the collective effort of everyone here, we could double what you have written in less than six months :)
Posts: 4,587
Threads: 105
Joined: Jul 2005
:-D
Anyway this label made it to the front page of the manual yesterday already. HTH.
Posts: 228
Threads: 7
Joined: Aug 2011
Sourceforge's wiki is MediaWiki - which is good.
Pauli created the wiki and added me to the editor group so I moved my toung-in-cheek user's guide to the WP-34s project wiki.
I started on a guidelines page and added a (blank) Todo page. If you want to contribute signup and get added to the editors group.
First items of business is to come up with an outline (table of contents) and upload all the nice little graphics (keys) that Walter and Pauli created for the reference manual.
I have an HP48SX and HP-15C manual, as well as PDFs of the HP32sII, HP-33s and HP-35s to use as style examples.
▼
Posts: 4,587
Threads: 105
Joined: Jul 2005
Quote:
... upload all the nice little graphics (keys) that Walter and Pauli created for the reference manual.
As a matter of fact, I created these "graphics" using Luiz Vieira's font - they are just plain and simple text. No witchwork :-)
Walter
Edited: 2 Oct 2011, 4:11 p.m.
▼
Posts: 228
Threads: 7
Joined: Aug 2011
Oh, very nice.
Nuts - don't think MediaWiki can use TTF - I guess that's a work item to cut an paste into little png files the keys so that they can be called up with [[File:f.png]][[File:H.d.png]]
Posts: 372
Threads: 42
Joined: Mar 2011
I don't know about others, but another problem I had with the manual is this:
it gets updated really often (fortunately) but there's no "changelog". And I'm not going to re-read the whole thing cover-to-cover every time an update is made. So sometimes I just miss some new information (I've been told RT(F)M myslef a while ago because I missed some info exactly this way).
But then, I also understand that managing a detailed changelog would take too much time. Oh well... :(
Cristian
▼
Posts: 3,229
Threads: 42
Joined: Jul 2006
I've noticed this too :-)
- Pauli
Posts: 4,587
Threads: 105
Joined: Jul 2005
Please see the very last page.
Walter
▼
Posts: 372
Threads: 42
Joined: Mar 2011
The last page is useful but I'm pretty sure (though not 100%) that the last page doesn't list *all* the changes; and anyway, if you skip updating for a few revisions, you definitely don't get all the changes. A simple changefile, updated rev by rev with what was changed in the latest rev, would be nice, again IMO.
Cristian
▼
Posts: 228
Threads: 7
Joined: Aug 2011
it can be almost as much work to keep the changelog updated as it is to do the update. That's why we're moved to wikis for a lot of our design documentation where I work. You want to know what Fred changed when he did that update 3 months ago, just click on the record in the history.
You can do the same thing with Word, but it's a lot more work to implement and is usually geared to reviewing.
Posts: 1,253
Threads: 117
Joined: Nov 2005
Quote:
"Objects in this mirror appear smaller than they really are"
From memory I think it's backwards:
"objects in mirrow are closer than they appear"
since the intent of the message it not to warn about the size of the object, but of the apparent sense of proximity - which is falsely interpreted by the person looking at the mirror.
What does this have to do with the posts, you may wonder? I think it's all a matter of perspective. I wrote the 41Z manual knowing that nobody would read it, yet I wanted to capture all possible information about the functionallity - not only the strict command description and staccatto instructions. Being a reference document makes it much more useful than a QRG or a dire enumeration of capabilities (and let it be clear that I'm not saying that's what the 34S manual is!).
I've read most of it even if I don't have any 34S yet - just because I wanted to learn more not about the machine, but about the project.
User manual vs. owners handbook - same precisions here in English...
▼
Posts: 3,283
Threads: 104
Joined: Jul 2005
Angél, writing documentation when one is involved in a project or even is the only person working on it is an integral part of the work because you have to rethink everything twice when you try to describe it in detail.
In our case the manual is not in the same hands as is the implementation which complicates thinks at times. Possible outcomes are changes to the code, changes to the documentation, or both.
▼
Posts: 776
Threads: 25
Joined: Jun 2007
Quote: Angél, writing documentation when one is involved in a project or even is the only person working on it is an integral part of the work because you have to rethink everything twice when you try to describe it in detail.
Hmmm....
In a small project like this, having the creators write the manual is probably inevitable.
However, I have a theory that manuals SHOULD NOT BE WRITTEN by the programmers, the makers, etc. of whatever - they are too close to the project, and may well assume too much. Even "thinking twice" may not be enough. A manual should be written by an outside, even naive, user. He'll need the insiders to help, of course, but he is more likely to stumble over the same problems that other new users will.
Similarly, software should be tested by somebody other than the programmer. That's why there are beta testers.
Guess a manual needs have beta readers!
▼
Posts: 3,283
Threads: 104
Joined: Jul 2005
Dave, I disagree. You may be right for a Beginner's Guide but creating a reference at the same time you are creating the function is very helpful in rethinking what the function really does.
▼
Posts: 776
Threads: 25
Joined: Jun 2007
I'll agree on the reference manual, but I think a users/beginners manual will benefit from being written by the user/beginner (under supervision!).
Posts: 3,229
Threads: 42
Joined: Jul 2006
Quote: I wrote the 41Z manual knowing that nobody would read it...
I've read it :-) Even most of the code.
- Pauli
▼
Posts: 3,283
Threads: 104
Joined: Jul 2005
Quote:
I've read it :-) Even most of the code.
Stealing complex algorithms? ;-)
▼
Posts: 3,229
Threads: 42
Joined: Jul 2006
Nope.
I wish I had culled a few complex algorithms however.
- Pauli
Posts: 1,253
Threads: 117
Joined: Nov 2005
I feel honored! (and suddenly worried about the inaccuracies that no doubt plage the document...)
I very much doubt you had any need to steal any algorithm, let alone those I used. But you may be interested to know that after a long procrastinating time, I finally re-wrote the function launchers within the 41Z using MCODE tables - instead of the pedestrian code I'd used until now.
The relevance of this is that I freed-up 265 bytes, which immediately I filled-up with a complex ZETA function (yes, using Borwein - plagiarized from JM Baillard, only with the 41Z complex stack twist). Still on the testing bench, but looking great!
Best,
'AM.
Posts: 756
Threads: 31
Joined: Aug 2010
I would hazard a guess that most Americans think the hot liquid warning is stupid. But then only in America would a plaintiff win a lawsuit because she got burned by said hot liquids. Blame the lawyers.
A former girlfriend of mine was in insurance and they got a monthly circular on litigation that was won and lost. One case involved several people trying to start a car. They could not get it started by pushing it so they had the brilliant idea to have two people sit on the hood of one car with their feet on the trunk of the other while one drove that car and a fourth sat in the dead car and tried to start it when it got up to speed. The cars separated, bounced, whatever, and the two people on the hood fell in between the two vehicles and had their legs crushed. They were suing the auto companies because there was no warning on the vehicle specifically suggesting that this was a bad idea. This would have been laughed out of court in any other country in the world if it even got that far.
Some Americans are always looking for the fast buck. A way to get something for nothing and lawyers are always happy to help.
I have had that experience myself. Many years ago I was involved in a car accident when I was rear ended on the highway. Within 24 hours I had received 10 calls from lawyers wanting to take my case. This is considered ambulance chasing and I believe that most states have laws against it but it didn't stop them. I was fine except for a stiff back for a few days so of course I didn't sue.
I used to race bicycles and a friend of mine had a terrible accident during a race and was never the same again. Even though we all knew the risks involved and had signed waivers (generally not worth the cost of the ink used) lawsuits started flying. Every cycling organization involved in putting on the race was sued including the president of the club personally (the driver of the car involved and the police--those that should have had the biggest share of the blame--were *NOT* sued) and during pretrial information gathering I was contacted by a lawyer trying to get me to say that racing was unacceptably dangerous and that it was the fault of the organizers. I told her that, yes, I had been scared on occasion during races. That charging along at 30+ MPH (50+ KPH) in a pack with inches to spare on all sides with many people that you had never met before in your life was sometimes scary and that anyone who didn't feel that way was an idiot but that this was *not* the fault of the organizers it was just the name of the game, so to speak. At any rate she quickly lost interest in me and I never received another call. The point is that some people refuse to accept responsibility for the own actions and decisions and so the legal climate is such that you see silly warnings on coffee cups. I will say that my friend was not the one suing since at this point he was still in a coma and later, much later, had to relearn how to tie his shoes. BTW, just as an aside, after this event and the lawsuits, road racing was almost killed off in Dallas, TX and the surrounding area for a number of years with all racing being relegated to criterium style closed courses because of the fear of lawsuits and the inability to get insurance coverage for events.
Cheers,
-Marwan
▼
Posts: 1,253
Threads: 117
Joined: Nov 2005
It's not about the US, it's human nature, afraid to say. That's all what it amounts to, if you reflect on it.
Edited: 30 Sept 2011, 2:30 p.m.
▼
Posts: 756
Threads: 31
Joined: Aug 2010
Perhaps. But here in the US there are two things working against us. The number of lawyers and laws that allow said lawyers to bring (often) baseless cases without fear of retaliatory action. From the point of view of the lawyer it is often just way too easy to sue--the only loss is usually time. Also huge judgments make the practice very lucrative for some while costing the society as a whole.
▼
Posts: 1,253
Threads: 117
Joined: Nov 2005
I totally share your point of view - but again, those "permissive" laws and opportunistic lawyers are just basking on people's wishes to either get even, or better yet obtain benefits from a certain adverse situation (in which they may or may have not been led by others). Lest not mention greed as another leiv-motif...
There are of course genuine cases of misconduct or abuse, and the law has always tried to protect subjects exposed to those. So I guess it's a balance, that it's now totally abused because (as you say) "there's nothing to lose, just sue and see if we win". If the plaintiff had to pay the full cost of a lost trial, I'm sure they'll think it twice, or thrice, or even more times.
In the old days we were told that with freedom comes responsibility, and that "you're responsible for your own mistakes", which implies don't put the blame (or liability) on others, or their omissions to provide a fool-proof environment where mistakes aren't possible. The way things are going - providing disclaimers and warnings for every feasible contingency one can foresee - will certainly lead to a paralysis in society, amongst a very uncomfortable enviroment to live on (namley: no freedom!)
My 0,00000000002 cents.
Edited to add: apologies for hijacking the original 34S thread :)
Edited: 1 Oct 2011, 4:52 a.m.
▼
Posts: 756
Threads: 31
Joined: Aug 2010
Posts: 228
Threads: 7
Joined: Aug 2011
Quote:
This was rather frustrating and I think for a new user it would be really annoying. So my suggestion is to change FIX, SCI, and ENG to change the calculator back to real mode if it's in integer mode.
Yes, I would like to see how that would work. Let us know when you have submitted a patch:
See How to build a wp34s load
▼
Posts: 228
Threads: 7
Joined: Aug 2011
In xeq.c cmddisp() I added add a call to op_float(NULL,NULL,OP_FLOAT) and my wp34s now resets to float mode when I enter any one of ALL, FIX, SCI or ENG.
I haven't yet figured out if there are any undesirable side effects as I don't use integer mode very much. Any ideas where I need to focus my testing? I'm very much a newbie with this code.
▼
Posts: 3,283
Threads: 104
Joined: Jul 2005
At least you were able to set-up a compiler environment. Have you done the emulator compile and the firmware compile? I'd be interested to know of any obstacles you had to pass during the installation of the tools. A short write-up of your way through it would be helpful for many here.
▼
Posts: 228
Threads: 7
Joined: Aug 2011
Windows environment was pretty simple - would have been even easier if I had seen your HHC slides before hand :-). I documented it here:
wiki4help - howto build emulator
Attaching the debugger to wp34sgui_d and setting a break point to xeq() was a piece of cake.
I do not yet have a cable but once I do I will figure out and document the MinGW and Yagarto installation. When I said "my wp34s" I was referring to the windows emulator, which has become my favorite virtual calculator, replacing Free42 and Bill Menees RPNCalc.
Fortunately I still have a WinXP laptop with a serial port.
Edited: 30 Sept 2011, 10:31 a.m.
Posts: 3,229
Threads: 42
Joined: Jul 2006
Quote: So my suggestion is to change FIX, SCI, and ENG to change the calculator back to real mode if it's in integer mode.
As a rule, we've tried to shy away from functions that do multiple things. The function does what it does and nothing more.
- Pauli
▼
Posts: 228
Threads: 7
Joined: Aug 2011
Quote:
As a rule, we've tried to shy away from functions that do multiple things. The function does what it does and nothing more.
I don't think this is one of those cases though.
If the calculator is in integer mode and the user hits FIX 4, it means they want to do H.d, FIX 4. In cases like this where it is unambiguous the calculator should automatically do the intermediate step (if there is time and memory space to do it).
Posts: 112
Threads: 9
Joined: Jan 2011
It seems that executing SCI ENG or FIX in Integer mode does cause that display mode to take effect once you return to DECIMAL mode. Is that how the 16C functions as well? My only other reference is the 48sx, but that accomodates reals and integers on the stack simultaneously.
Posts: 203
Threads: 29
Joined: Nov 2009
Hmmmmmm Description of H.d:
Quote:
Takes x as hours or degrees in the format
hhhh.mmssdd and converts them into a decimal
time or angle.
Says nothing about changing the display or mode.
A while back we changed FIX to switch from fraction display back to decimal display. I don't see a problem or contradiction using it to leave integer or any other base back to decimal.
Posts: 528
Threads: 40
Joined: Dec 2008
Wow, I didn't mean to start a flame war. Let me respond to some of the things said here so far.
Pauli Wrote:
Quote:
As always, there are other issues to consider:
* Do all these five commands need to switch out of integer mode? Should they?
* Is making these functions have such a side effect a good thing or not? Simple functions are almost universally better than double barreled ones.
* What other side effects will happen here? One I know of is that H.MS display will be lost.
Changes like this usually have subtle side effects which aren't obvious.
and
Quote:
As a rule, we've tried to shy away from functions that do multiple things. The function does what it does and nothing more.
These are very valid points. A change like this could break programs that don't expect the side effect. It would have to thought through carefully.
At the same time, I think I've found another argument for making SCI, FIX and ENG change to decimal mode: the BASE function changes the integer base and switches to integer mode. I think one could argue that changing the integer base is somewhat analagous to changing the decimal display format, and thus all such functions should change the mode or none of them should.
Gene's "rant" (his word) about the manual is valid to a point. Clearly the documentation isn't what a "normal" calculator user would expect, but I don't fault Pauli or Walter for that at all. In fact, I'd encourage them to continue to produce this sort of terse-but-accurate reference guide. Frankly, I'd much rather have them working on the code than on the documentation. To me, it makes sense for someone (or a group) of other people to create a more user-friendly manual. I'd hope that the development team would allow this by releasing the keyboard font, but I don't think they really need to do more than this. Again, let them concentrate on the code. By the way, I have a Microsoft Word document that contains many of the elements of the Voyager series manuals. It would make a nice jumping off point for a 34C manual.
Egan writes:
Quote:
".d" is neither clever nor obvious. On the 16C it's "FLOAT". Given the lack of space "FP" may have worked too.
For better or worse, I believe that the keyboard is practically set in stone at this point for the simple reason that many people have already purchased and applied Eric's overlays.
Brian Walsh writes:
Quote:
[Pauli's response to the original post] wasn't just RTM, it was RTFM, which in this forum where people are hopefully trying to help each other I find unacceptable.
For what it's worth, I'd just like to say that I wasn't at all offended by Pauli's response. I'm from New Jersey where hurling insults is considered casual banter. :)
Dave
▼
Posts: 3,229
Threads: 42
Joined: Jul 2006
Quote: For what it's worth, I'd just like to say that I wasn't at all offended by Pauli's response. I'm from New Jersey where hurling insults is considered casual banter. :)
It was Walter not me who wrote that. I rarely if ever use that abbreviation. Please attribute things correctly :-)
BASE doesn't just change to integer mode. Read the manual :-) It can also change to floating point and fractions mode. More a side effect of the way commands with arguments are implemented than anything else but that is what it does.
Further food for thought: what about WSIZE or the four sign mode commands? Shouldn't these also cause a change to integer mode if executed? What about DEG/RAD/GRAD? Should they switch to real mode? D.MY, Y.MD and M.DY? They mandate reals as input, is a mode switch here in order? The complex prefix? SIN, COS, TAN? SL, SR, RRC? I'll stop myself at this point but I'm sure there are plenty more commands that could be defined as causing a mode switch and things would be a right mess if we did so for all of them.
Finally, to clarify what seems to be a misconception or lack of knowledge of the project's history, I was originally responsible for all of the code. Walter is in charge of the layout and the manual. I wrote originally because others have joined in on the coding side of things (Marcus predominately). I do, however, agree that a more user friendly manual would be nice.
- Pauli
Posts: 553
Threads: 57
Joined: Sep 2006
Don't apologize. You're just saying things everyone else is thinking. That's totally okay!
Bruce
▼
Posts: 3,229
Threads: 42
Joined: Jul 2006
:-)
I agree that H .d isn't the most obvious way back to real mode.
I'm just not sure that FIX et al are either.
- Pauli
▼
Posts: 3,283
Threads: 104
Joined: Jul 2005
H.d and H.ms have a history, they were originally conceived as counterparts: Switch to H.ms mode and back. We eventually got rid of the only half heartedly implemented H.ms mode which left H.d a bit orphaned on the keyboard.
I think it's a good idea to let ALL, FIX, SCI and ENG return the calculator to DECM mode. At least it's what I tried first until I figured out about H.d.
Pauli has explained how the coding had been done for the most time of the project: just by him. When I started digging into his work I discovered many places where I would have done things differently. In the meantime I've had the chance to implement some of my suggestions myself but not without starting a discussion among us whether my changes (mostly keyboard related) were a good idea or not. It's a matter of "Let go!" to your baby when it grows up. (The same may hold for the documentation.)
|