Using Reference for Beginners
prof_braino
Posts: 4,313
References for Beginners
The investigation and experiment
There is a recurring situation where a question is posed, and the answer already exists in the references.
In some cases the answer is complex and possibly "hidden"; in other case completely obvious, and could have been found by cursory inspection. In EITHER case, the response could be (at best) a precise answer; to "it's in the references" (a weak answer); to RTFM (Read The Freakin' Manual, you maroon[sic]). This last response is the poorest answer, and (in my opinion) is MUCH worse than asking any "stupid" question in the first place.
Rather than argue what's worse and why, some of us (jazzed and I) have decided to explore this as an opportunity to make improvements. I'm kind of big on "process" and "training". I thought I would start an experiment to see if we could make a training for beginners on how to use the references before asking questions. Yes, I know its probably a fools errand, but you never know until you try, we might get lucky.
When a question arises, suppose there are two main causes:
1) the references do not present the information correctly or clearly, in which case the references can be improved
2) the "asker" does not know how to use the existing references correctly, in which case the "training" might be improved
This discussion will proceed to explore cause 2, training improvements. If other root causes are identified, those can be examined also. Cause 1, improvements to the references, need not be included in this discussion, as this already occures.
It is widely assumed that anyone with any experience in technology will have experience in using references, and failure to use the references is unacceptable. While this may be true, beginners, by definition, can NOT be assumed to have any experience with anything.
Inexperience with references could be the case with a) kids, or b) non-techinal adults, or c) overly smart folks that have always managed to figure everything out by looking at it, and have never needed to use a manual before. This last, overly smart folks, create the biggest problem, since they are hard to argue with; so the intent of this thread is to gear the training towards kids. In doing so, this can also be applied to non-technical adults, potentially the parents of the kids, as the kids should have support from parents or other adults. This suits my purpose, if this needs to be expanded or modified it can be addressed.
The investigation and experiment
There is a recurring situation where a question is posed, and the answer already exists in the references.
In some cases the answer is complex and possibly "hidden"; in other case completely obvious, and could have been found by cursory inspection. In EITHER case, the response could be (at best) a precise answer; to "it's in the references" (a weak answer); to RTFM (Read The Freakin' Manual, you maroon[sic]). This last response is the poorest answer, and (in my opinion) is MUCH worse than asking any "stupid" question in the first place.
Rather than argue what's worse and why, some of us (jazzed and I) have decided to explore this as an opportunity to make improvements. I'm kind of big on "process" and "training". I thought I would start an experiment to see if we could make a training for beginners on how to use the references before asking questions. Yes, I know its probably a fools errand, but you never know until you try, we might get lucky.
When a question arises, suppose there are two main causes:
1) the references do not present the information correctly or clearly, in which case the references can be improved
2) the "asker" does not know how to use the existing references correctly, in which case the "training" might be improved
This discussion will proceed to explore cause 2, training improvements. If other root causes are identified, those can be examined also. Cause 1, improvements to the references, need not be included in this discussion, as this already occures.
It is widely assumed that anyone with any experience in technology will have experience in using references, and failure to use the references is unacceptable. While this may be true, beginners, by definition, can NOT be assumed to have any experience with anything.
Inexperience with references could be the case with a) kids, or b) non-techinal adults, or c) overly smart folks that have always managed to figure everything out by looking at it, and have never needed to use a manual before. This last, overly smart folks, create the biggest problem, since they are hard to argue with; so the intent of this thread is to gear the training towards kids. In doing so, this can also be applied to non-technical adults, potentially the parents of the kids, as the kids should have support from parents or other adults. This suits my purpose, if this needs to be expanded or modified it can be addressed.
Comments
The goal is to provide a beginner with sufficient training to use existing references, and then to ask specific questions to experienced users. The criterion for success is that the question gets a specific answer, and the responder does not feel the need to respond with a non answer (eg RTFM). Since "feel the need" is subjective, only the "specific answer" can be used as a valid statistic measure for success. The ultimate goal is to direct askers to a source that builds their confidence in presenting questions in the manner we all expect and prefer. (reword this last sentence)
So what is needed to train up a beginner to properly use the references? Off the top of my head, I can come up with this list:
* Definitions that the beginner will not already know.
* List of references the the beginner is expected to be referencing
* List of topics that are commonly asked by beginners
* Examples of using the references to answer common problems
My thought is the lists of definitions and references should be as complete as possible. The topics and examples can initially be sparse, until a need for expansion is demonstrated.
At this point, don't worry about PRESENTATION of the material, that will be covered later. The initial discussion should focus on CONTENT.
For our purposes, we tend to use these terms as follows. Depending on context, these terms may have other meanings, though less common. This list should be quite large.
* Reference - any source of answers, and the act of going to a source for answers
* Documentation - Any source that records information on the subject, intended as a re-usable reference.
* Manual - a particular reference in the documentation, i.e, a "handbook" usually containing the word "Manual" in the title. NOTE: this term can also be used generically to refer to the entire set of references, as in RTFM. The context of Manual vs Automatic is discussed elsewhere.
* Datasheet - the official technical summary of the operation and use of a part or subsystem, as provided by the manufacturer. These usually follow a specific format, but the format has evolved over time. (true?) Variations are discussed on a case by case basis.
* Standard - an agreement among knowledgeable users on how something is usually done. These are usually named and published when strong agreement exists; and not closely adhered to when weak agreement exists. In any case, exceptions can found depending on context.
* Best Practices - an agreement that a particular set of options should be favored for reason of safety, reliability, ease of maintenance or use, etc. These tend to be specialized, newer, or more volatile than Standards.
* Application - This refers to "applying the prop to do job". This usually involves interfacing the prop to external hardware, writing code to make them talk, and a user interface so a user can examine and control the prop that the external hardware.
* App Notes, Application Notes - These are examples of connecting the prop chip to specific external hardware and making them function together. (an application).
Please post or PM to contribute to the list of definition a beginner needs to know.
This list should be quite large.
[To obtain the propeller chip]
* Bare chips - http://www.parallax.com/Store/Microcontrollers/PropellerChips/tabid/142/List/0/CategoryID/18/Level/a/SortField/0/Default.aspx
* Mounted on boards - http://www.parallax.com/Store/Microcontrollers/PropellerDevelopmentBoards/tabid/514/List/0/CategoryID/73/Level/a/SortField/0/Default.aspx
* General info - http://www.parallax.com/propeller/
[Included in the Prop tool]
* Propeller Quick Reference - a "cheat sheet" that names all the command and control symbols for SPIN and PASM, and general layout of the part. While this does not include detailed explanation, it is useful to keep it handy while working.
* Propeller Manual - (link) This is the main reference for propeller instructions, both SPIN and PASM. This should be checked first for each issue with a particular instruction. This is also provided in the Help option of the Propeller tool
* Propeller Data sheet - (link) - this is the concise technical summary for the prop chip. It include physical and operational characteristic of the part. Casual user will generally not need this reference till later, but eventually you will have questions that this will answer. This is also provided in the Help option of the Propeller tool
* Propeller Demo Board Schematic - (link) this show the "standard" physical connection for the prop for some common functions. These physical connection are not mandatory on other hardware, and other configuration are common. This provides a point of reference using on a set of physical configuration and thus an start on modifications for custom configurations.
* Propeller Eduction Kit PDF - (link) Examples of using the prop with just a bread board and minimal components. Even if you don't have an official PE Kit, this is the place to start. This can be used with the PE Kit, the Demo board, the Pro Development board, and any other general prop hardware. NOTICE: Even though this is at the bottom of the Help tab in the propeller tool, THIS IS WHERE YOU START. Specifically, chapter 3 is where we start plugging in parts and getting stuff going. You probably ought to read Chapters 1 & 2 as well, but this is the "dive in" point.
* The Propeller general information page http://www.parallax.com/propeller/
* Propeller Q&A http://www.parallax.com/portals/0/help/P8X32A/QnaWeb/ - does the search work?
* prop wiki http://propeller.wikispaces.com/
* Propeller FAQ [ is there one yet? ]
[Included in the Application Notes]
http://www.parallaxsemiconductor.com/appnotes
Should the list be repeated here so it is easier to do a text search on this page?
[Data sheets for commonly use external parts]
List list might include each specific part used in the OBEX?
(EEPROM)
(Crystal)
(FDTI)
(CP1202)
Please post of PM to contribute to the list of reference a beginner will eventually use.
Please focus on the minimum necessary and sufficient for use of the propeller and peripheral peripherals;
i.e. thanks in advance for suggesting Websters dictionary, etc; but we have bigger targets closer to the mark to address first.
[Question beginners tend to ask]
How do I set up a serial connection?
[Useful general applications.]
Serial connect example.
I'm thinking to update the preceding posts as folks add their input.
If you think this is unnecessary, please do not post, and let the thread fade down the list.
Even though it would be repeatious, starting with categories and working down the common paths people go would probably draw more folks to the references.
Can this be covered by including "categories" with "Topics" in entry #6, and an example (if available) in entry #7, or do you something different in mind?
good idea in general. I think I did understand the main-purpose of training unexperienced people young or old how to find and use written information
that they can help themselves as often as possible.
Particular on FAQs
My personal experience with FAQs is: Whenever I used FAQs I did not find a question that used my words how I would ask it.
So I think it is important to find a way to include all kinds of keywords that could be in relation with the topic
In case of serial connection this could be
V24, V-24, RS232, RS-232, COMport, serial-LCD, serial-printer, serial-scanner, serial-device, USB-to-serial
using two propeller-IO-Pins to transfer / transmit send / receive data and even some more.
Of course reading through so many words might be annoying too. So a solution could be a thesaurus-paragraph
that is easy to recognise as a thesaurus-paragraph
for the rest of it
If you can provide examples of how kids asked in a untrained way. These examples would be a good base for me to explain how the asking can be improved.
Maybe your intentions are different. If so please explain more what you waht to have
keep the questions coming
best regards
Stefan
I thought I would practice a bit with this. I'm assuming a certain level of literacy and ability and trying very hard to follow this guideline "The goal is to provide a beginner with sufficient training to use existing references, and then to ask specific questions to experienced users. The criterion for success is that the question gets a specific answer ...."
Hi new user. Welcome to the forum!
The Propeller Tool Menu has a wonderful getting started document called Propeller Education Kit (pdf) or "PE-Kit". You may not have the PE-Kit hardware, but the PE-Kit document is easy to read and has a serial port setup in chapters 2 and 3 that shows the basics for any hardware.
The PE-Kit document is also available on line. Version 1.1 which has easy to navigate bookmarks is available here.
Some Propeller hardware has a USB serial port and others have a 4 pin connector that needs the PropPlug. The PE-Kit shows using a PropPlug and a Propeller on a bread-board. Don't let the breadboard scare you ... it's just a different kind of a Propeller setup that some people prefer.
Please have a look at the PE-Kit document. Don't hesitate to ask more questions.
I hope I don't disturb the great organization you've brought to the problem or prompt a brawl.
I want quick answers, and the PM isn't organized that way. It's not like a PIC, ARM, or AVR users manual. I find the PM more useful now than when I started. IMHO the PM absolutely sucks as a way to learn PASM, but isn't too bad as an adjunct to getting up to speed with SPIN, although there are far too many words. I'll never read all the words in the PM as long as I live. Sorry, but that's just how it is. No amount of RTFM insults will change that reality.
I think there is a need for a PASM manual that puts something like this...
VAR long Shared 'Shared variable (Spin & Assy) PUB Main | Temp cognew(@Process, @Shared) 'Launch assy, pass Shared addr repeat <do something with Shared vars> DAT org 0 Process mov Mem, PAR 'Retrieve shared memory addr :loop <do something> wrlong ValReg, Mem 'Move ValReg value to Shared jmp #:loop Mem res 1 ValReg res 1...on freaking Page 1 and then proceeds to explain each point. At about Page 4 or 5, I'd put something like a simplified version of FullDuplexSerial (take out the polarity options, for example) and proceed to discuss the new concepts it introduces....
This is the sort of presentation that would ultimately draw me to the PM for further enlightenment.
Edit: I guess what I'm describing is a heavily edited version of deSilva that has the imprimatur of Parallax.
1. I had been out of electronics and computers on the most part for 4 years.
2. Forums were new to me and the forum search engine back then was virtually unusable.
3. I was not familiar with the wiki.
4. Searching for anything (terms was also a problem) wasn't yielding much.
5. I was an experienced programmer and designer with a lot of micro experience on older micros.
6. I did follow the manual examples. They were a great intro.
I know a lot of the various places for references has been improved. The tutorials have improved. I haven't looked at the sticky to see what is there.
I think an FAQ is one way to go... Just the question and a link to the answer. This way, the user can search through the FAQ list quickly. It can be subdivided into sections with links at the top list to the sub lists further down the page.
FAQs often solves the problem of not knowing how to ask a question. Correct or common terminology is often unknown.
A really good online tutorial is also a good way. If it progresses correctly, then some sections can be skipped. I am not sure what is out there now, so perhaps some comments from the newer members would help here.
There definately seems to be something required, because as you say, there are a lot of similar questions continually being raised.
The very first thing is the idea that there are, in fact, references. The kinds of references are: People, works, things, reasoning tools.
The second thing is the idea that one needs to know where their understanding is not inclusive. This is hard. IMHO, it's harder than coming to understand references, because it involves knowing how to reason.
A beginner will know their understanding is not inclusive, but may well be confused as to how to proceed. Secondary confusion will be over what is a reference, and most importantly, what that reference is good for. Matching those up with the questions, gaps in understanding, is the primary task at hand for any beginner, because they need to know how to learn more, or suffer application by rote, or some other strictly limited thing.
How to use a reference really boils down to how to learn more, and do so in a way that is self-correcting, so that the learning can build to competency, and eventually mastery and authority. ie: becoming a reference
Becoming a reference is actually a great way to understand how to learn, what needs to be learned, why it matters, and so on... It's that directional compass that helps process the information in ways that are productive.
Once one gets there, the next best thing is to find those people who are references and model their behavior, asking questions and here's the potatohead secret sauce: meta-questions!
The answer to the direct question is in most cases secondary. The process by which the answer was rendered is primary. I don't think that's communicated very well at all in most contexts, and where that kind of query isn't encouraged, we end up with people who know a lot of stuff, but cannot parse the stuff they've accumulated to build on that effort, limiting them to mastery within the scope of things they've seen, not things they themselves have reasoned. (edited recently, review last sentence for changes.)
Long ago, in my primary school education, I had a mentor who conveyed what I just wrote, and it was a very significant thing to come to understand. I would add this to your how to use references discussion, along with a primer on critical thinking, both kinds: inference and deduction. The idea that there can be "general rules" inferred from data points acquired from references is a powerful one, necessary when one is attempting mastery at a new discipline.
Yes, the same kinds of questions are being raised. IMHO, the single most important thing we can do is characterize those, produce one reference that details both the answers, and the process by which we regularly arrive at those kinds of answers, and introduce it to newbies.
I would suggest a welcome wagon kind of approach, done via e-mail, after a new member sign up. Hit 'em with one a day for a week or so. In those e-mails, introduce our current references, why they matter, who produced them, and general approach for getting good answers to their specific questions.
A PM could be used too, as could a ramp down, one a day, then one a week, then one a month, then one when a significant reference is established, as a broadcast to the community as a whole.
Pre-Internet, my single most potent means of finding and understanding the applicability of various references was to look at what was fit to "broadcast", however that was most easily done at that time and in that niche. Those references matter, and understanding which ones matter is also a very significant thing to know, because it speaks right to successful processes, and or solid reasoning, both of which are important to reaching mastery of a discipline.
And this is a bit redundant, given my post above, but right there is a great case for applying inference! Say there are a few great references. What common elements of reason do they employ, if any? And how do they process new questions? Some thought given to those yields a ton in a very short time, because it very directly answers "how to proceed" for the beginner.
I'm thinking that after we get the content established, the information could be collected from this thread and planted in a web page.
The text from post #12 would be a good candidate for the start of that page, it is prbably all many folks will need.
This is interesting, I thought I was the only one
Don't worry. We should highlight disagreements, and exampine them to respolve the conflicts. These hold the key to progress.
This is important. This is how many of us think, it is NOT unique to "those darn kids today". I imagine that a certain segment of the population are simply wired this way, and while "inconvenient" for regular folks, should be considered if we want to include a larger audience. So, we have to make a new manual organized for "folks who don't like to read the manual", or teach folks how to read a manual organized different from "how they think", or some combinarion.
I really like that you posted this.
Ah ha! Now we have evidence that this path has been traveled before! The famous deSilva again. Now I feel we are in good company. Can you please provide a couple links to the materials you have in mind? I began participating in this forum after deSilva stopped posting.
This is great, we are getting evidence that even the most capable members can have issues with the docs. If Cluso99 has "difficultly" I would expect to be hopelessly lost. As I was.
So we are on the track of something that may be of benefit to at least some portion of the population.
I would think that a FAQ should already exist, didn't I see one before?
The prop general information page
http://www.parallax.com/propeller/
has Q&A
http://www.parallax.com/portals/0/help/P8X32A/QnaWeb/
but this is not very friendly to me, I don't think the search work?
I imagine a FAQ should be a single, comprehensive, search-able list so we can find stuff.
I know there is a prop wiki http://propeller.wikispaces.com/ but this seems spare and there are no dates. I can't tell if its active or not. Is this even used anymore? It looks dead to me.
I guess I should add these links and a description for each to post 5 References.
Very interesting. One technique I use (go figure) and teach my kids, is to help others with the most difficlut subject. That is, if a subject is very difficult for me, I start a study group to help others learn. By trying to teach it, I learrn it better myself.
My presentation is verbal, I have to do the timeing and waving hands and facial experessions to may it work. How do we turn the sentiments from post 15 into something that works on a kid (or any beginner) in written form? Or is it fine as it is? To me it seems post 15 is bigger than one post.
This is great ...."the process by which the answer was rendered".. I love this!
But how to put this into practice? Who can do this? I have exactly enough time for all the things I already do, I would have to trade some of those for these; the wife would have, shall we say, "input" on the matter.
There are a LOT of intermediate pages between a landing page and final destination page.
Depending on what path one happens to choose, one may miss many options.
The identifier for a given destination page is not always clear. While "propeller manual" is probably the first thing I would try when looking for the propeller manual, "AN0001" is not the first thing I would try when looking for anything.
I am getting the idea that a large part of the "references" issue is simply the learning curve on where things are located. After three years, I still don't know where all the references are located, I have to google for some string that will hopefully get me close, and drill down from there. If I don't come up with a search string that gets me the match I want, after a few tries I imagine no reference exists. I do recall stumbling across things months later, but I do not recall the exact items.
So, would this issue be addressed by a searchable uber-list of of all the references, as proposed in post 5? Or is there a better alternative?
Probably that should be a discussion involving Parallax. I can see the initial "on-boarding" done in a scripted way, with the source material updated from time to time to account for new developments. It would be interesting to have that e-mail go to everybody, say once a month or so. "New developments", with the goal being to just keep people up to speed on the state of the references, etc.. The "on-boarding" would serve the purpose of getting newcomers tuned into that.
Back before Internet, I would often consult the popular periodicals to achieve a similar effect. One gets to know who the players are, terminology, references, products, etc... that way. Today, the same would be true through forums, web, and a e-mail or other broadcast kind of thing that's not very intrusive.
...as would mine, though I could find some time to help contribute to this. Won't be effective, unless endorsed though. That's why Parallax should be part of this discussion, IMHO. They are in the position of being a reference on references. A great alternative would be somebody well known, like OBC, who is promoting anyway. Others could fill this role too, I'm just citing him as a very easy example, while also trying not to rope him in, out of hand.
So there is a "on-boarding" program, that leads to participation in the community, and consumption of "the news letter" which continues the conversation over the longer term, much like we do anyway. IMHO, not everybody has the time or inclination to follow the goings on here, a lot is missed, unless people are really looking.
As for post #15, yeah there is a lot there. And I do a similar thing, always trying to learn new information with the idea of sharing it with others. Personally, I think that gets right at those very important meta-questions, "the process by which the answer is rendered". That's built in for me, teased out by that mentor years ago, and part of my default behavior, in that I often pay attention to other people I find worthy of that attention, seeking to understand how they do what they do, not always the product of what they do. If that can be captured successfully, many scenarios then can be handled without having to ask for or accumulate a lot of rote understanding. Reason is cheaper than bulk memory for me. Always has been.
I don't know if that is true for everybody though. IMHO, that would be a very intriguing meta-conversation for the "sandbox" here.
You asked about how to convey #15. Well, I answered the question, "How to determine truth" in a discussion a while back, just kind of off the cuff, citing my experience in simple form.
Maybe it's useful in this discussion:
1. If it's gonna be accepted as true, it's gotta be defensible, meaning it would pass core reasoning analysis. That means nothing circular, incomplete, self-referential, etc... In short, rational.
2. Is the scope of it inclusive enough? We really have large gaps in our understanding of things. That means we have a fair number of things on the table that really cannot be established as absolutely true. So scope really matters. True enough has got to be a consideration. Inference helps here by framing things up with basic rules that can serve to reason with, until more is known.
3. Does the body of established facts support it? This kind of goes with scope really. If the body of facts is inclusive, there is no opinion really. For everything else, there is!
4. Who are the authorities? This ties into things being self-referential. Easy thing to slip into without knowing. For robust pieces of information, you will find the authorities are well referenced with said references crossing many political, technical, and social boundaries.
Avoid the think tank circle jerk. What I mean here is there are often references who form a closed loop. These are to be avoided as authorities, unless their material can be fact checked with the greater peer-reviewed discussions. Edit: It can be hard sometimes to differentiate a "think tank" kind of contrived set of closed references from what is maybe just a pool of interested people, doing something outside the norm, forming a closed loop because they are in a niche. Our community is a bit like the latter. Still authoritative, just not well referenced otherwise.
5. People. What are their motivations, who is paying them, why? These things, and related ones, do not in and of themselves, discredit information they provide, but they may well escalate how diligently you pursue fact checking on them.
6. It may be that a given bit of information cannot be evaluated true or not. In that case, you are left with a value judgement. That being true or not then depends on what you value. In the scope of generalities, it comes down to what groups of others value and why.
So that is my general process for establishing references, and vetting ideas. Sometimes it takes a while, particularly if the material is new to me. Any beginner on any discipline would do very well to understand this rough dynamic. It is quite literally how to learn how to learn, and know what is learned makes sense.
Iterating on those elements, not necessarily in order, just inclusiveness, leads to one becoming a reference authority, simply because that which is learned is well vetted, correctly reasoned, and as such will be authoritative. Great way to self-learn, IMHO. (most of my life learning has been exactly that as being a busy adult does not often allow for much else!! So, I'll spend my commute time thinking through stuff, reasoning to distill it down to the core elements, saved for when I have time to explore them.)
These ideas are also good for simply establishing value. Truth may or may not be applicable or possible. Value always is.
On another note I am a Beginner/Hobbyist I have thought that there should be a Example Code in the OBEX with examples provided by Parallax or anyone who wishes to teach. The examples could expand on the basic examples in the Manual which many new people say are not explained well.
An Example of what I am talking about would be CASE for instance in the manual almost all the examples use the same statement "case X+Y" there is a few more examples. It isn't clear to the newbie that there are a lot more ways to use it like " Temp =: ina[0..3] / CASE Temp / %0001 : FlashLED " you get the idea. Now a new guy will eventually discover the other ways to use the commands by looking at other code, which isn't always easy to read or well commented. I know the OBEX isn't everyones favorite place to search but at least everything would be in one place.
Sorry I know this is about "Reference for Beginners" but this was also on my mind.
Ron
After looking at some code, and finding code means looking through a lot of code just to find case in it, and hopefully not get distracted, I ended up seeing how it can be used. Actually just avoided it for a while because of that.
Your other suggestions are great, IMHO.
This is where the leader/manager/teacher/boss make a list of "this is what you need to know to do this" for the first person to be brought in on the job. The assignment is for the new guy to use these notes to get started, and update the notes with anything the original person missed. When the new person is able to do the job correctly, the 'notes list is put to bed.
When another person is brought on, the leader does NOT have to re-do the notes. The leader directs the current new person to the previous new person. The instruction is, "Update the 'notes with whatever we added since then, and turn them over to the new guy with the same instructions I gave you".
This way, the person that needs the information has the most accurate version, and a source to turn to for finding corrections etc. Questions propigate back up the list until they get an answer.
This was the peer-level training method at one of the most successful outfits I worked at. Anybody else see it? Any ideas on working something like this into n00bie instructions?