Using Reference for Beginners

[prof_braino]

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.

[prof_braino]

Goal:

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)

[prof_braino]

Requirements:

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.

[prof_braino]

Definitions:
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.

[prof_braino]

LIST OF Applicable REFERENCES:

This list should be quite large.

[To obtain the propeller chip]
* Bare chips - http://www.parallax.com/Store/Microc...0/Default.aspx
* Mounted on boards - http://www.parallax.com/Store/Microc...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.

[prof_braino]

LIST OF TOPICS
[Question beginners tend to ask]
How do I set up a serial connection?

[prof_braino]

LIST OF EXAMPLES
[Useful general applications.]
Serial connect example.

[prof_braino]

This is what I've been thinking about all morning. If anybody has any ideas, please post.

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.

[Ragtop]

As varied as the things people can do with electronics, I am thinking the hobbyist either comes in with something they want to do or finds themselves at least at the start drawn to a certain category: robotics, communication, video, etc.......

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.

[prof_braino]

As varied as the things people can do with electronics, I am thinking the hobbyist either comes in with something they want to do or finds themselves at least at the start drawn to a certain category: robotics, communication, video, etc.......

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?

[StefanL38]

Hi braino,

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

[jazzed]

LIST OF TOPICS
[Question beginners tend to ask]
How do I set up a serial connection?

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.

[K2]

Prof,

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.

[Cluso99]

When I started on the prop some 3 years ago, I found it very difficult to find anything. The reasons were varied..
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.

[potatohead]

Well, I'm thinking back to my early experiences. Pre-Internet, meaning books, what I can observe and experience directly, who I can talk to, what I can reason.

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.

[potatohead]

Re: Cluso's post above.

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.

[prof_braino]

Hi new user. Welcome to the forum!

The Propeller Tool Menu ....... Don't hesitate to ask more questions.

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.

[prof_braino]

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.

This is interesting, I thought I was the only one

...or prompt a brawl.

Don't worry. We should highlight disagreements, and exampine them to respolve the conflicts. These hold the key to progress.

I want quick answers, and the PM isn't organized that way.

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.

Edit: I guess what I'm describing is a heavily edited version of deSilva that has the imprimatur of Parallax.

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.

When I started on the prop some 3 years ago, I found it very difficult to find anything. The reasons were varied.. FAQ...

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.

[prof_braino]

.... understanding is not inclusive. ... ie: becoming a reference

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!

[prof_braino]

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.

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.