I usually rely on the quickstart guide that's been folded up like a roadmap. After I'm done with installation/assembly, I give my wife the quickstart guide, manual, special wrenches that were included along with the spare parts, and she files them away for future reference. Then after 10 or 15 years we go through the file cabinet and realize that we still have the quickstart guide, manual, special wrenches that were included along with the spare parts, and we no longer have the device that it came with. We then remove the plastic wrapping from the manual that was never opened and throw it in the recycling bin.
I checked sometimes, but I mostly read the manuals. I don'tlike reading, so I never read novels (not even at school - only the cribs).
So, I do read most manuals, except the TV, VCR, HDTV Tuner, etc - I am not interested in using these with anything other than the basics - and if I need to I can ask my wife to record a show.
But I read the whole Chip manuals that I want to look at and perhaps use.
So when my friend wanted to convert his VB programs (a commercial system) from VB6 to VB.NET he bought me the book and a highlighter. Normally this worked in the past, because I read the manuals, highlighting the noteworthy items. He would then just read the highlighted sections. Didn't work on VB.Net because at the beginning of the book I realised I wasn't interested. And I have still resisted VB.Net.
I don't mind reading, but I do find that new topics have new jargon and new concepts that are generally presumed fundamentals.
To that end, I prefer the following for an entirely new subject:
A. Read an introduction that is well written, preferably about 50 pages, certainly less than 100 pages.
B. Read a more in depth text, 200 or 300 pages from a well accepted author
C. Read anything authoritative, including tomes of 500 or more pages.
For some reason I cannot fathom, I can't find anything less that 500 page of Java and many other OOP languages. So why bother?
For learning C, there is a nice original tutorial that was written by Richie and less than 50 pages, there is the ANSI C Manual that is 190 pages of text plus another 50 or so of appendices, and then there are all those tomes that are so big I don't want to carry them with me on the bus or in a car. Learning C is much more pleasant.
I am also dismayed by on-line new rather than in-print news.
Newspaper editors positioned stories, decided on their space and location by how important they felt the subject was. Once can scan the whole paper or magazine (I subscribe to The Economist) to get a sense of what is relevant to the publisher and editors. But reading The Wall Street Journal on line is a chaotic tyranny of having one story after another thrown at you, and to make matter worse -- Google working with The Wall St. Journal might just be providing you with the news they think you want to hear.
In sum, the information age is becoming and Information Dark Age as computers have become the advertising portal extraordinaire.
It is no longer merely 'Buyer Beware', it is also 'Reader Beware'.
English being an open language that borrows words from just about any languge means that the word 'saloon' likely originated from the French 'salon' and the cowboy's and working girls were just trying to pretend that they were in a high-class French salon.
But it all comes down to meaning a sitting room of sorts, on a boat, in a car, or in a stationary structure. I suppose you can have a salon or a saloon in your Learjet if you can get enough people to say it is that.
Advertisers just love to revive odd usage to get attention. And branded product just love to create their own terms and not use the same as the competition's terminology. This MS manuals go to great lengths to avoid sounding like Linux or Apple. The want to keep their customers dumb and too broke to afford learning how to change to another brand.
In other words, if you want to learn a new subject -- be willing to sort out what people are really saying regardless of how they say it.
But the truth is I just can't follow much of MS's documentation -- it seems they are telling me [a] ask a friend, hire and expert, [c] don't ask us unless you have very deep pockets and are willing to still be clueless.
"Documentation" is really not meant to be read, just referred to. It's reference material, usually top-down, and is only there if/when you need it. Not many people have read their car manual cover to cover. In a well-designed car, they wouldn't need to read the section on how to use the seat belts.
Tutorials and how-tos are meant to be followed more-or-less from start to finish, though not everyone needs the hands-on approach, and not everyone needs to complete all the tutorials.for a product. Like dressing in layers to accommodate changes in the weather, tutorials in "layers" let users choose how much or how little they're comfortable with.
I've never read the documentation for a microcontroller all the way through. It all has to be there as reference, and available on tap, but end-to-end? If I'm a newbie to microcontrollers I might get a book about the generalities of using and programming one, but that's not documentation. Or I might get a "cookbook" to show me specific solutions, but I'm unlikely to read all the recipes, or want to make them all.
...In a well-designed car, they wouldn't need to read the section on how to use the seat belts...
I did read the seat belt section for a new car I bought. And was surprised to learn that the seat belts have an electrically activated "charge" in them. This causes the seat belts to tighten at the time of an accident.
But you didn't have to read the manual to use the seat belts. That's the important distinction. Recreational reading (cuz you're simply interested) is a whole 'nother subject. I sometimes read the sides of cereal boxes, but reading isn't a requirement to enjoy the contents.
The Urban Legend about only %5 of people read instructions originated with the early Xerox Copier's success. Supposedly Xerox spent something like five million dollars in research on how to write the best user manual for their copiers. The guy who did the research claimed that 95% of all users did not read the manual, just asked a friend how to use the device.
That's interesting. Sal said this is the number he has observed several times in his career, they even did there own study.
It also rings true to experience. I noticed that the best engineers read the docs, at least enough to find what they need later. Other-than-best engineers don't read the manuals until the last resort, this might be related to the other-than-best impression. Non-engineers tend to avoid manuals.
From this, one might surmise that we should tailor the manuals to full-on engineers? Except for cases like Ikea, with a simple pictures instead of words.
Yes, that rings true for me as well. One of the areas I get involved with at various companies is tech pubs. They take engineering data, documentation from various departments, sometimes the actual product, sketches and whatever else they can scrape together to produce "the manual" or whatever it is.
A whole lot of companies are moving away from this, instead using video, audio and hypertext to produce things that are easy to navigate, compelling and highly visual. Part of the value of whatever the product is lies in how accessible it is, and that is a function of design, engineering and documentation. These days, products that require volumes of documentation in order to use just aren't considered accessible. Typically, that is compensated for with serious capability that makes training, reading, education investments worth it. Said products typically target higher end use cases where there is enough money in the whole thing for it to make sense.
Anything that's aimed at the masses just won't do well. Now, that's consumer type product experience mostly, but it does apply to niche things for various disciplines too. The other factor driving this is access to people! Distilling things down means more ordinary general purpose people can employ whatever it is and that is just lean throughout the whole cycle. Very attractive.
HP was one of the first to really start down this road with entirely visual documentation for a lot of it's products. The first time I encountered that, it was strange. Literally nothing to read! For the average use case, that was all people needed. Unpack it, assemble it, connect it, then do three easy things, done. Product in use. For those actually wanting the more advanced features, the documentation came far less attractive in it's formatting, but entirely useful for those so inclined. Interesting split.
On the other extreme are slickly produced videos and documents that anybody can pick up and understand, and that's it! They simply make the device discoverable enough that the advanced things are self evident to those who go looking, or who would know about those functions and features in the first place!
(and yes, due to length, you are correct when you assume I do write docs --that and education materials and presentations all the time)
In the context of a micro-controller, I find this a hard problem. There are just too many axis. People may or may not have foundation knowledge. They may or may not have advanced use cases. They may or may not be readers. Interestingly, they may or may not be interested in too much learning, as opposed to just doing. I think that's the point the Arduino people got that a whole bunch of us didn't. Sometimes people just want to do stuff. Enabling them to just do stuff opens the tech up to a ton of people who would not attempt to use it otherwise.
When I read something Chip writes about a Propeller, I find remarkably few words and those words do detail how the device works to a very high degree, but they also assume a lot of general understanding too. Electrical principles, circuits, techniques, programming, etc... When I read some of the Parallax material, far fewer assumptions are there, and of course the education focus makes this the right move, but then again there is a lot of ground to cover. Indexes and such help with this, as does style where things can be read in chunks. I will read something Chip wrote, then go off on a little online adventure to fill in the various gaps, clarity coming then, not on first reading where it something I have not worked with before.
Then I see people with use cases that just aren't gonna be in either set! Props are general purpose things with a lot of capability brought to bear on various problems. One common thread was "need documentation on video" for P1. We saw this over and over, and but for some real edge cases Kurenko explored to great effect, the general documents were enough to understand the code, and the code out there really was the documentation! Not all that accessible. However, documenting that in a way that makes things accessible requires covering video signals, PASM, electronics to understand circuit possibilities, typical input cases for TV, LCD, VGA, others, and finally techniques! Lots of 80's era graphics tricks make a P1 shine, but where are those documented? Most often, those are documented in code, and or old books that may or may not have the detail needed to use a Propeller.
There are other cases like this, it's just that I was confronted with the video one enough to comment on. Others I am sure can cite their own observations.
My conclusion goes back to the three levels:
1. Pure technical feature / function (Chip and others writing to the core attributes)
2. Education / advanced user / learner (Parallax education, cook books and such) 3. Magic!***
It's the magic that is hard. It requires lots of things come together, and each bit of magic could actually use it's own book, but the appeal for each bit isn't general purpose enough to warrant such an effort, so we end up chatting about things, reading code and peeking between the cracks to see where the magic is and how it might work and if we really get after it, the magic is something we can invoke and share.
Perhaps strong efforts to distill the first two cases into something simpler free time and energy that can be applied to the magic. I don't know. IMHO, those efforts would be much better spent figuring out how to optimize the sharing of magic once discovered so that people can find where it's been discussed, look at code, and generally get to the center of understanding on that quickly, where ever and however that ends up being expressed.
From P1 video, the example would be WHOP, which is that hand off point where the data from D & S gets fetched into the video generator. I can't even put that into clear terms without a paragraph, but suffice it to say, that's one artifact of the chip not really documented in precise detail, though the hand off was, and the code we have out there, along with a few discussions is the documentation. If somebody finds it, reads it, tracks the threads, runs the code, they can get at that particular magic and employ it for very efficient video projects. But they might not even know to look, and that's the problem to solve IMHO, more than it is a better traditional document.
Perhaps assembling traditional documents out of that solution, from time to time, makes much better sense than trying to figure out what it all might look like before people go off and discover stuff like that.
***Arthur C. Clarke defined this term differently, and that's my intent here embodied in his three laws:
Clarke's Three Laws are three "laws" of prediction formulated by the British writer Arthur C. Clarke. They are:
When a distinguished but elderly scientist states that something is possible, he is almost certainly right. When he states that something is impossible, he is very probably wrong.
The only way of discovering the limits of the possible is to venture a little way past them into the impossible.
Any sufficiently advanced technology is indistinguishable from magic.
Whatever happen to the Product Sales Engineer? That used to pay about twice what a regular engineering job would pay, because he would actually help the customer (okay the big customers) understand how the product fits into their needs.
First we got 'the manual', and now we 'get the compelling video'. Yuck.
That's my point, though I make the suggestion the best learning is through your own discovery, made possible because the core product or concept is presented in a way that allows for intuitive learning.
Manuals are there for getting started and reference, but the best way to learn is to discover things about it yourself. Seat belts -- as a simplistic example -- are self-discoverable even without the pictograph or flight attendant showing you how they work.In the domain of microcontrollers, some programming languages are more discoverable than others. They invite experimentation, rather that learning by rote.
A good manual for a well designed product is not intended to be read linearly, so by definition you don't "read" it; you use it on demand. I have a rather thick manual for my TV. I've never read it, or felt the need to. But I have consulted certain sections when I needed more information about a feature that wasn't obvious.
So I talked to the Physicist on the team (degree in physics, programs in C, did not read the docs, was stuck). He finally read the docs after the play ground lady was able to do the activites by reading the docs. She was motivated to read the docs after the fourth graders were able to do the activities.
The physiscist said that now that he's reading them, the are easy. However, he did not read them at first, because he had no point of reference, and when he started, he could not tell if they made sense or not. And/or we was "scared" in some way. This might be important.
Something like, we need somebody to get us started. After we establish a point of reference, via mentor, etc. things can make sense in in terms of that first exposure. Then we can read the material on our own. The face-to-face or side-by-side intro event -might- be the secret ingredient.
Maybe this isn't the right way to express this thought. Any ideas?
There is a very strong argument that learning a 2nd language actually makes one smarter.
After all, expecting everything to be written in the same style that your high school or university English teachers recommended in just not going to work in a modern world.
One has to expand their knowledge to a general understanding of semantics, and most often a contrasting 2nd language is the best way to see the usefulness of doing so.
There is a very strong argument that learning a 2nd language actually makes one smarter.
After all, expecting everything to be written in the same style that your high school or university English teachers recommended in just not going to work in a modern world.
One has to expand their knowledge to a general understanding of semantics, and most often a contrasting 2nd language is the best way to see the usefulness of doing so.
I agree, but consider. Boy Chance (the physicist) speaks English, Spanish, Russian, and a few others, as well as Klingon, Vulcan, and couple other SciFi language to the extent they can be spoken outside of fiction. Messes up my "languages makes you smarter" theory.
This poll started as in regards to the LittleRobot pilot program at an elementary school. I'm trying to get a feel for how much documentation to expose the students to, and what to expect from the students.
The kids seem to respond the same as the adults: an individual item should have the shortest possible explanation, and shortest exact working code that demonstrates the item. Kids can't stay focused for things that run longer, and adults won't stay focused longer, than the minimum to express the material. There are a few exceptions that just read and read, and fewer that read and retain everything; but the majority seem to like "short".
After they do the work and move on, kids (and adults) will ask for more detail later, if they want it. If its in a face-to-face situation, they will just blurt out the question, and I can answer it. If it is NOT face-to-face, they will still blurt out the question, but I will not be there to hear it, and answering remains a challenge. Folks tend NOT to ask "simple detail" questions through delayed media, and these questions are often not simple nor detail, but fairly complex and important. So I still have to figure out a way to handle these. This may simply require the brute force effort of getting (probably hiring) a profession editor to re-organize and clarify the wiki pages.
This poll started as in regards to the LittleRobot pilot program at an elementary school. I'm trying to get a feel for how much documentation to expose the students to, and what to expect from the students....
Braino,
I think asking elementary kids to deal with documentation is very different than asking adults to deal with it. At that age, I'm guessing you need to show and tell and provide cool demos rather than hand them a stack of paper and tell them RTFM. I would never expect kids in that age group to read "documentation" of that sort. Of course, there might be an exceptional child who is either very motivated or perhaps under the lash of a Tiger Mother, but for the most part it just hain't gonna happen.
I'm guessing your poll results might have turned out a little differently if you had mentioned the elementary school thing.
With the advent of microcontrollers with free compilers, a lot of documentation has tried for a big 'wow factor' to drive popularity and sales rather than any true educational mission.
When I try to teach microcontrollers to young kids, I find that they often need to start with learning what electricity does with magnets, what a switch is, how circuits run in circles, and more.
So I feel that often the entry point, and the coverage are hit and miss.
If you are going to write to any audience, you really have to understand your audience. And to write to a wide audience, you have get away from jargon and special terms... towards presenting topics in generic English with everyday examples.
Reader's Digest has long claimed to be the highest circulating English magazine in the world. It does so by holding to a standard of good 10th grade English. Not university level English, not even high-school graduate. But that's how you reach a wider audience.
How old are we talking about? And what level of complexity?
When I was nine years old I was given a Philips Electronic Engineer kit (not by accident I had been begging for it).
I could read the instructions well enough to build the light detector, radio and other circuits with that, and they worked. I was well into trying to tweak around and add to the circuits. Adjusting them a bit here and there for whatever purpose.
However, in that kit was a more detailed manual with proper looking schematics, and fuller descriptions of how those circuits worked. Despite pouring over it 99% of it made no sense what so ever. It was another year or so before I found someone who could answer my questions and get me jump started on that.
Comments
Oh my God. I know that story well. We still have draw full of special wrenches for who knows what.
So, I do read most manuals, except the TV, VCR, HDTV Tuner, etc - I am not interested in using these with anything other than the basics - and if I need to I can ask my wife to record a show.
But I read the whole Chip manuals that I want to look at and perhaps use.
So when my friend wanted to convert his VB programs (a commercial system) from VB6 to VB.NET he bought me the book and a highlighter. Normally this worked in the past, because I read the manuals, highlighting the noteworthy items. He would then just read the highlighted sections. Didn't work on VB.Net because at the beginning of the book I realised I wasn't interested. And I have still resisted VB.Net.
To that end, I prefer the following for an entirely new subject:
A. Read an introduction that is well written, preferably about 50 pages, certainly less than 100 pages.
B. Read a more in depth text, 200 or 300 pages from a well accepted author
C. Read anything authoritative, including tomes of 500 or more pages.
For some reason I cannot fathom, I can't find anything less that 500 page of Java and many other OOP languages. So why bother?
For learning C, there is a nice original tutorial that was written by Richie and less than 50 pages, there is the ANSI C Manual that is 190 pages of text plus another 50 or so of appendices, and then there are all those tomes that are so big I don't want to carry them with me on the bus or in a car. Learning C is much more pleasant.
I am also dismayed by on-line new rather than in-print news.
Newspaper editors positioned stories, decided on their space and location by how important they felt the subject was. Once can scan the whole paper or magazine (I subscribe to The Economist) to get a sense of what is relevant to the publisher and editors. But reading The Wall Street Journal on line is a chaotic tyranny of having one story after another thrown at you, and to make matter worse -- Google working with The Wall St. Journal might just be providing you with the news they think you want to hear.
In sum, the information age is becoming and Information Dark Age as computers have become the advertising portal extraordinaire.
It is no longer merely 'Buyer Beware', it is also 'Reader Beware'.
At the following, "saloon" is not only a bar/tavern, but also a room on a ship and a sedan car (U.K.)...
http://www.thefreedictionary.com/saloon
A saloon car...
http://www.independent.co.uk/life-style/motoring/motoring-news/volkswagen-updates-jetta-saloon-2004357.html
Exactly. As I said no surprises there. Just common everyday usage.
Well living in the US, a saloon car was news to me!
But it all comes down to meaning a sitting room of sorts, on a boat, in a car, or in a stationary structure. I suppose you can have a salon or a saloon in your Learjet if you can get enough people to say it is that.
Advertisers just love to revive odd usage to get attention. And branded product just love to create their own terms and not use the same as the competition's terminology. This MS manuals go to great lengths to avoid sounding like Linux or Apple. The want to keep their customers dumb and too broke to afford learning how to change to another brand.
In other words, if you want to learn a new subject -- be willing to sort out what people are really saying regardless of how they say it.
But the truth is I just can't follow much of MS's documentation -- it seems they are telling me [a] ask a friend, hire and expert, [c] don't ask us unless you have very deep pockets and are willing to still be clueless.
"Documentation" is really not meant to be read, just referred to. It's reference material, usually top-down, and is only there if/when you need it. Not many people have read their car manual cover to cover. In a well-designed car, they wouldn't need to read the section on how to use the seat belts.
Tutorials and how-tos are meant to be followed more-or-less from start to finish, though not everyone needs the hands-on approach, and not everyone needs to complete all the tutorials.for a product. Like dressing in layers to accommodate changes in the weather, tutorials in "layers" let users choose how much or how little they're comfortable with.
I've never read the documentation for a microcontroller all the way through. It all has to be there as reference, and available on tap, but end-to-end? If I'm a newbie to microcontrollers I might get a book about the generalities of using and programming one, but that's not documentation. Or I might get a "cookbook" to show me specific solutions, but I'm unlikely to read all the recipes, or want to make them all.
-- Gordon
I did read the seat belt section for a new car I bought. And was surprised to learn that the seat belts have an electrically activated "charge" in them. This causes the seat belts to tighten at the time of an accident.
Here is a what a seatbelt "Pre-Tensioner" looks like...
http://www.youtube.com/watch?v=kxN6hsf6KQk
-- Gordon
That's interesting. Sal said this is the number he has observed several times in his career, they even did there own study.
It also rings true to experience. I noticed that the best engineers read the docs, at least enough to find what they need later. Other-than-best engineers don't read the manuals until the last resort, this might be related to the other-than-best impression. Non-engineers tend to avoid manuals.
From this, one might surmise that we should tailor the manuals to full-on engineers? Except for cases like Ikea, with a simple pictures instead of words.
Can an "Ikea manual" be make for the prop?
Could it be that this forum is populated by that 5%? It seems it might be reasonable...
I wonder what a similar poll would get on the Home Depot or Best Buy forums...
That's because they show you how to do it on TV and threaten you with fines if you don't. "Click-it or Ticket".
One person's manual might just be a TV to someone else LOL. The point is that we all learn things one way or another.
A whole lot of companies are moving away from this, instead using video, audio and hypertext to produce things that are easy to navigate, compelling and highly visual. Part of the value of whatever the product is lies in how accessible it is, and that is a function of design, engineering and documentation. These days, products that require volumes of documentation in order to use just aren't considered accessible. Typically, that is compensated for with serious capability that makes training, reading, education investments worth it. Said products typically target higher end use cases where there is enough money in the whole thing for it to make sense.
Anything that's aimed at the masses just won't do well. Now, that's consumer type product experience mostly, but it does apply to niche things for various disciplines too. The other factor driving this is access to people! Distilling things down means more ordinary general purpose people can employ whatever it is and that is just lean throughout the whole cycle. Very attractive.
HP was one of the first to really start down this road with entirely visual documentation for a lot of it's products. The first time I encountered that, it was strange. Literally nothing to read! For the average use case, that was all people needed. Unpack it, assemble it, connect it, then do three easy things, done. Product in use. For those actually wanting the more advanced features, the documentation came far less attractive in it's formatting, but entirely useful for those so inclined. Interesting split.
On the other extreme are slickly produced videos and documents that anybody can pick up and understand, and that's it! They simply make the device discoverable enough that the advanced things are self evident to those who go looking, or who would know about those functions and features in the first place!
(and yes, due to length, you are correct when you assume I do write docs --that and education materials and presentations all the time)
In the context of a micro-controller, I find this a hard problem. There are just too many axis. People may or may not have foundation knowledge. They may or may not have advanced use cases. They may or may not be readers. Interestingly, they may or may not be interested in too much learning, as opposed to just doing. I think that's the point the Arduino people got that a whole bunch of us didn't. Sometimes people just want to do stuff. Enabling them to just do stuff opens the tech up to a ton of people who would not attempt to use it otherwise.
When I read something Chip writes about a Propeller, I find remarkably few words and those words do detail how the device works to a very high degree, but they also assume a lot of general understanding too. Electrical principles, circuits, techniques, programming, etc... When I read some of the Parallax material, far fewer assumptions are there, and of course the education focus makes this the right move, but then again there is a lot of ground to cover. Indexes and such help with this, as does style where things can be read in chunks. I will read something Chip wrote, then go off on a little online adventure to fill in the various gaps, clarity coming then, not on first reading where it something I have not worked with before.
Then I see people with use cases that just aren't gonna be in either set! Props are general purpose things with a lot of capability brought to bear on various problems. One common thread was "need documentation on video" for P1. We saw this over and over, and but for some real edge cases Kurenko explored to great effect, the general documents were enough to understand the code, and the code out there really was the documentation! Not all that accessible. However, documenting that in a way that makes things accessible requires covering video signals, PASM, electronics to understand circuit possibilities, typical input cases for TV, LCD, VGA, others, and finally techniques! Lots of 80's era graphics tricks make a P1 shine, but where are those documented? Most often, those are documented in code, and or old books that may or may not have the detail needed to use a Propeller.
There are other cases like this, it's just that I was confronted with the video one enough to comment on. Others I am sure can cite their own observations.
My conclusion goes back to the three levels:
1. Pure technical feature / function (Chip and others writing to the core attributes)
2. Education / advanced user / learner (Parallax education, cook books and such)
3. Magic!***
It's the magic that is hard. It requires lots of things come together, and each bit of magic could actually use it's own book, but the appeal for each bit isn't general purpose enough to warrant such an effort, so we end up chatting about things, reading code and peeking between the cracks to see where the magic is and how it might work and if we really get after it, the magic is something we can invoke and share.
Perhaps strong efforts to distill the first two cases into something simpler free time and energy that can be applied to the magic. I don't know. IMHO, those efforts would be much better spent figuring out how to optimize the sharing of magic once discovered so that people can find where it's been discussed, look at code, and generally get to the center of understanding on that quickly, where ever and however that ends up being expressed.
From P1 video, the example would be WHOP, which is that hand off point where the data from D & S gets fetched into the video generator. I can't even put that into clear terms without a paragraph, but suffice it to say, that's one artifact of the chip not really documented in precise detail, though the hand off was, and the code we have out there, along with a few discussions is the documentation. If somebody finds it, reads it, tracks the threads, runs the code, they can get at that particular magic and employ it for very efficient video projects. But they might not even know to look, and that's the problem to solve IMHO, more than it is a better traditional document.
Perhaps assembling traditional documents out of that solution, from time to time, makes much better sense than trying to figure out what it all might look like before people go off and discover stuff like that.
***Arthur C. Clarke defined this term differently, and that's my intent here embodied in his three laws:
Clarke's Three Laws are three "laws" of prediction formulated by the British writer Arthur C. Clarke. They are:
First we got 'the manual', and now we 'get the compelling video'. Yuck.
That's my point, though I make the suggestion the best learning is through your own discovery, made possible because the core product or concept is presented in a way that allows for intuitive learning.
Manuals are there for getting started and reference, but the best way to learn is to discover things about it yourself. Seat belts -- as a simplistic example -- are self-discoverable even without the pictograph or flight attendant showing you how they work.In the domain of microcontrollers, some programming languages are more discoverable than others. They invite experimentation, rather that learning by rote.
A good manual for a well designed product is not intended to be read linearly, so by definition you don't "read" it; you use it on demand. I have a rather thick manual for my TV. I've never read it, or felt the need to. But I have consulted certain sections when I needed more information about a feature that wasn't obvious.
For instance, counting that starts with 0 instead of 1.
Or a True condition is 0, while a False is anything other than 0.
Or the fact that the serial interface for a keyboard and a mouse uses a 13 bit packet in one direction and a 12 bit packet in the other.
Or how the numbers you use for your internet addresses are expressed 196 025 001 001.
Sure, there is an explaination for each and every one of these things, but it takes a lot of time to figure out what is what in each context.
The physiscist said that now that he's reading them, the are easy. However, he did not read them at first, because he had no point of reference, and when he started, he could not tell if they made sense or not. And/or we was "scared" in some way. This might be important.
Something like, we need somebody to get us started. After we establish a point of reference, via mentor, etc. things can make sense in in terms of that first exposure. Then we can read the material on our own. The face-to-face or side-by-side intro event -might- be the secret ingredient.
Maybe this isn't the right way to express this thought. Any ideas?
After all, expecting everything to be written in the same style that your high school or university English teachers recommended in just not going to work in a modern world.
One has to expand their knowledge to a general understanding of semantics, and most often a contrasting 2nd language is the best way to see the usefulness of doing so.
I agree, but consider. Boy Chance (the physicist) speaks English, Spanish, Russian, and a few others, as well as Klingon, Vulcan, and couple other SciFi language to the extent they can be spoken outside of fiction. Messes up my "languages makes you smarter" theory.
Not sure about smarter, but learning another language can certainly broaden one's perspective.
The kids seem to respond the same as the adults: an individual item should have the shortest possible explanation, and shortest exact working code that demonstrates the item. Kids can't stay focused for things that run longer, and adults won't stay focused longer, than the minimum to express the material. There are a few exceptions that just read and read, and fewer that read and retain everything; but the majority seem to like "short".
After they do the work and move on, kids (and adults) will ask for more detail later, if they want it. If its in a face-to-face situation, they will just blurt out the question, and I can answer it. If it is NOT face-to-face, they will still blurt out the question, but I will not be there to hear it, and answering remains a challenge. Folks tend NOT to ask "simple detail" questions through delayed media, and these questions are often not simple nor detail, but fairly complex and important. So I still have to figure out a way to handle these. This may simply require the brute force effort of getting (probably hiring) a profession editor to re-organize and clarify the wiki pages.
Braino,
I think asking elementary kids to deal with documentation is very different than asking adults to deal with it. At that age, I'm guessing you need to show and tell and provide cool demos rather than hand them a stack of paper and tell them RTFM. I would never expect kids in that age group to read "documentation" of that sort. Of course, there might be an exceptional child who is either very motivated or perhaps under the lash of a Tiger Mother, but for the most part it just hain't gonna happen.
I'm guessing your poll results might have turned out a little differently if you had mentioned the elementary school thing.
When I try to teach microcontrollers to young kids, I find that they often need to start with learning what electricity does with magnets, what a switch is, how circuits run in circles, and more.
So I feel that often the entry point, and the coverage are hit and miss.
If you are going to write to any audience, you really have to understand your audience. And to write to a wide audience, you have get away from jargon and special terms... towards presenting topics in generic English with everyday examples.
Reader's Digest has long claimed to be the highest circulating English magazine in the world. It does so by holding to a standard of good 10th grade English. Not university level English, not even high-school graduate. But that's how you reach a wider audience.
When I was nine years old I was given a Philips Electronic Engineer kit (not by accident I had been begging for it).
I could read the instructions well enough to build the light detector, radio and other circuits with that, and they worked. I was well into trying to tweak around and add to the circuits. Adjusting them a bit here and there for whatever purpose.
However, in that kit was a more detailed manual with proper looking schematics, and fuller descriptions of how those circuits worked. Despite pouring over it 99% of it made no sense what so ever. It was another year or so before I found someone who could answer my questions and get me jump started on that.