Shop OBEX P1 Docs P2 Docs Learn Events
Poll: Who Reads Documentation? - Page 3 — Parallax Forums

Poll: Who Reads Documentation?

13

Comments

  • LoopyBytelooseLoopyByteloose Posts: 12,537
    edited 2013-05-23 07:53
    jazzed wrote: »
    Not sure about smarter, but learning another language can certainly broaden one's perspective.

    One starts with learning another language, sooner or later one shifts to what is language and then what is meaning, and finally where is the meaning conveyed.

    When one views the world in terms of where and what is the meaning, the results are usually more interesting and profound.

    I started my Chinese studies at 47 and thought I pretty well knew what English was. Now I am 65 and quite astonished with all that I learned in the last 18 years... just because I was willing to look at a completely different systems of communication.

    That wider view that one gets, just continues to get wider and wider... and wider.

    BTW, I did start in on computer languages to compare them with natural languages. A computer language is NOT as profound as a living language in use by a large segment of the world's population.
  • mindrobotsmindrobots Posts: 6,506
    edited 2013-05-23 08:26
    So far, my 4-H efforts are faltering for a number of reasons:

    1) lack of preparation on my part
    2) not having age appropriate materials
    3) not engaging the kids
    4) not always having the right sized "chunk of project" for the available work period

    Things that worked versus things that didn't:

    1) soldering the Freeduino boards was a hit
    2) building the robot chassis was a hit
    3) discussing the differences between Propeller and Arduino and deciding which to use that was a snoozer!
    4) any attempts at discussing programming - snooze time! I wasn't talking at the kids level - need to work BIG TIME on this

    Key Learnings to date: (Key Learnings makes it sound so professional :smile:)
    - engage the kids
    - give them an end goal for the session (or a couple intermediate goals with tangible accomplishments
    - bite sized pieces
    - addressed to their level (the multi-core discussion may have lost them! :smile:)
    - hands on
    - FUN!
    (those last two feed back directly to engagement)

    Now, as for the PropForth Wiki - it's a great dumping ground for scattered and random thoughts, experiments, detail and miscellaneous information. It is not a great structured reference or place to dump someone out a a tutorial experience. Yes, it needs to be restructured but I don;t want to lose the dumping ground and scattered thought area that the wiki is now (I think in scattered thoughts and projects).

    There probably need to be two tutorials (easy to say when we don't even have one yet!): a kid's LittleRobot version (adults can read ti too!) and a more adult (filled with hearty tales of when Forth programmers sailed the seven seas!) version of a general PropForth/Forth tutorial.

    That's where my head is now.
  • KC_RobKC_Rob Posts: 465
    edited 2013-05-23 08:35
    Define "read"? LOL I skim the docs first, looking for highlights and potential gotchas, but rarely read them front to back before doing anything.
  • potatoheadpotatohead Posts: 10,261
    edited 2013-05-23 08:46
    Yep. Me too. I think that counts as "read" :)

    I wanted to riff a little on what Prof_Braino said: "Need somebody to get us started"

    This is actually all about shared context. One of the hardest things to grok when picking up a new task is how they, with "they" being those adept at the task, think about it. Context.

    One of the things I always read is introduction, words of wisdom, kinds of things written by those in the know to those seeking to know. That helps a lot with context, and it's often fairly easy to follow through because there is almost always some narrative or other that gets a person through. In a very real sense, this is just like that mentor introducing the task.

    When I am bootstrapping myself like that, I seek, in order of value:

    1. Some real time with an experienced person

    Professionally, people regularly pay large sums of money for this. A few hours or a day or two with somebody who knows the stuff cold, able to interact, demonstrate, etc... is pure gold. Very rapid learning and competency happen.

    2. Real time dialog with same voice, chat, web meeting

    3. Real time dialog with others in general, which can still be very helpful

    4. Dialog that isn't real time, e-mail, forum, etc...

    5. Anything written by experienced people

    6. The actual reference docs.
  • prof_brainoprof_braino Posts: 4,313
    edited 2013-05-23 08:46
    I think asking elementary kids to deal with documentation is very different than asking adults to deal with it. ...
    I'm guessing your poll results might have turned out a little differently if you had mentioned the elementary school thing.

    The stuff that works with kids also works with adults. The stuff that doesn't work with adults also doesn't work with kids. This is the only thing I am sure about at this point.
  • potatoheadpotatohead Posts: 10,261
    edited 2013-05-23 08:50
    In line with my post above, kids have two core differences from adults, well three:

    1. Can apply considerable amounts of low distraction time to the problem. Adults may be able to do this, but typically cannot or won't.

    2. Much fewer preconceptions. As adults, where we can learn to seek that curious state where it's fun to play, learn, etc... we do much better. Often what we think we know gets in the way as adults where kids are more willing to observe, consume do.

    3. Interaction with peers. Kids will just chat about it on any level, few worries. Adults won't always do this and again, that is another skill worth working on. Having basic questions is natural, but we generally don't like to admit that, which gets in the way.
  • prof_brainoprof_braino Posts: 4,313
    edited 2013-05-23 08:51
    Heater. wrote: »
    How old are we talking about? And what level of complexity?

    3 @ 4th grade (~10 years old)
    4 @ 5th grage (~11 years old)
    1 @ ~24 years old
    2 @ ~45 years old

    Complexity is all the pages with "LittleRobot" in the title. Some weere a hit, others a miss, as recorded in the notes.

    http://code.google.com/p/propforth/w/list

    The rest of your post rings true with what I observe here.
  • prof_brainoprof_braino Posts: 4,313
    edited 2013-05-23 09:03
    mindrobots wrote: »
    faltering for a number of reasons:

    1) lack of preparation on my part

    Problematic, we work for free between jobs. If we try too hard we are doing it wrong. maybe.
    2) not having age appropriate materials

    If it works for kids, it should work for adults. I'm exploring this.
    3) not engaging the kids

    The teachers advised me to focus on PLAY activites, this works well. If it doesn't look like play it needs to be re-packaged.
    4) not always having the right sized "chunk of project" for the available work period
    I have two folks helpiung me "chunk" the material, we haven't got it down yet.

    Things that worked versus things that didn't:

    1) soldering the Freeduino boards was a hit

    Interesting, we were forbidden from solder, safety rules. My 5 year old solders fine.
    2) building the robot chassis was a hit
    here too
    3) discussing the differences between Propeller and Arduino and deciding which to use that was a snoozer!
    same
    4) any attempts at discussing programming - snooze time! I wasn't talking at the kids level - need to work BIG TIME on this
    Programming was an instant hit. Hello World resulted in dozens of variations of Jimmy-> " smells bad" etc
    Blinky LED resulted in a jump to looping and delays. One kid spontaneously start making sequential LED flashes, and taught this to the old kids, per "New Guy Notes" method.
    Key Learnings to date
    same

    - FUN!
    (those last two feed back directly to engagement)

    There probably need to be two tutorials (easy to say when we don't even have one yet!): a kid's LittleRobot version (adults can read ti too!) and a more adult (filled with hearty tales of when Forth programmers sailed the seven seas!) version of a general PropForth/Forth tutorial.

    This is a good idea. I will start on this now.
  • prof_brainoprof_braino Posts: 4,313
    edited 2013-05-23 09:06
    KC_Rob wrote: »
    Define "read"? LOL I skim the docs first, looking for highlights and potential gotchas, but rarely read them front to back before doing anything.

    I think this is the best case we can expect, on average.
  • prof_brainoprof_braino Posts: 4,313
    edited 2013-05-23 09:11
    potatohead wrote: »
    3. Interaction with peers. Kids will just chat about it on any level, few worries. Adults won't always do this and again, that is another skill worth working on. Having basic questions is natural, but we generally don't like to admit that, which gets in the way.
    This is interesting. The most successful company I worked for introduced me to "New Guy Notes", the new guy becomes maintainer of the training notes. Each successive new guy becomes trainer of the new new guy. Each new guy rates the trainer for effectiveness.

    This goes with the idea that knowledge is not power, rather the TRANSFER of knowledge is POWERFUL. Knowledge is useless unless it goes from the party that has it to the party that needs it, in a timely manner. If I can teach these kids to "de-silo" their information, the world will become a slightly better place.
  • prof_brainoprof_braino Posts: 4,313
    edited 2013-05-23 09:14
    @potatohead: your best posts are always too long for a post. We should talk over beer.
  • potatoheadpotatohead Posts: 10,261
    edited 2013-05-23 09:19
    Well yes!

    That is precisely it. I've seen a shift in this which is really good. The tendency for adults is to hoard things for job security reasons. The fact that we have hammered on working adults with so much job competition and automation enables this behavior. Can't blame 'em.

    Slowly, I'm seeing the ability to seek and acquire mastery and share it become a more pervasive norm. My own behavior has always been this way, and I simply landed in job scenarios where that matters. Doing pre-sales stuff right now is perfect. I'm always digging into something and once I've mastered it, I then want to talk about it! The ugly side is framing it in business terms, which is what they pay me for of course.

    The other element here is having basic insecurities. I did have to make this transition as a young adult. Was constantly worried about not being an equal peer. Slowly, I realized that basic, humble, curious character with the intent to get it done bigger, better, faster, stronger (yeah, daft punk reference), is most important and peers pick up on that and once it catches a great environment forms where people can be themselves seek what they need to, share what they don't.

    For many adults, who have not experienced that culture, it's just hard. Many inhibitions cause either avoidance or long discouraging hours trying to get it on their own so they don't have to ask or reveal a weak spot.

    Older school companies can be problematic. Many newer school ones get this and have dealt with it.
  • potatoheadpotatohead Posts: 10,261
    edited 2013-05-23 09:20
    Did you say beer?

    Well, there is SKYPE and I can drink mine, while you drink yours! I can PM you a SKYPE name, and we can do it in the near future, unless you are near PDX, Oregon. Ahh Chicago. Well, I'm sometimes in that part of the country, but usually slammed. Let's do SKYPE.
  • Heater.Heater. Posts: 21,230
    edited 2013-05-23 09:28
    Braino,
    @potatohead: your best posts are always too long for a post. We should talk over beer.
    Can I come? I'll sit in the corner and keep quite. Honest.
  • mindrobotsmindrobots Posts: 6,506
    edited 2013-05-23 09:38
    Key Learning:

    LittleRobot(tm) Skype and Beer Working Group

    (googling for anti "Drink and Skype" campaigns.....)
  • mindrobotsmindrobots Posts: 6,506
    edited 2013-05-23 09:41

    Interesting, we were forbidden from solder, safety rules. My 5 year old solders fine.

    Wow! I'm glad I didn't ask anyone for permission!! :innocent:

    I think I only got one, "OUCH! That's HOT!!"
  • LoopyBytelooseLoopyByteloose Posts: 12,537
    edited 2013-05-23 10:05
    The stuff that works with kids also works with adults. The stuff that doesn't work with adults also doesn't work with kids. This is the only thing I am sure about at this point.

    Seems to be ignoring the stuff that works with adults and doesn't work with kids... the not quite ready to be learned.

    @Mindrobots
    1. It is a lot easier to teach kids physics that programming. Have you noticed that when the lessons get tactile and physical, they are more interested?

    Of course soldering is easy to teach a 5 year old.
    A. Their parents are afraid of it. .. big attention getter and motivator.
    B. It is tactile.
    C. You may be the first kid to do it as the other parent's said "No." .. big boost in status within your peer group.

    Thats why I keep saying that a robotics class should start with disassembly of a DC motor. And that electro-magnetics needs to be taught before you get into micro-controllers, including relays and switching.

    Failure to start 'at the level the students really need' is quite common in language classes. I remember the first week in Taiwan and one student wanted to teach me Chinese by having me read all the characters from all the signs on the street -- too advanced, pure overload.

    2. Programming is abstract -- like mathematics.

    There are very good reasons we wait until junior high or high school to teach these subjects. Rather than earlier teaching by rote and exercise, we begin to chain ideas together into more elaborate forms of knowledge.

    3. Learning to be a teacher requires experience.

    While anybody can make lesson plans, the first few years is full of having them fall apart one after another. Some are good, but a lot are too long and too ambitious. Others are way too short and you have to bring out your reserve of jokes and games to keep the class from figuring out you don't know what you are doing.

    But eventually, you begin to get in synch with presenting what you want, covering it all over a period of time, and actually having the kids love you for what they learned.

    In other words, the beginning is brutal --- even with a university degree and a teaching certificate.
  • potatoheadpotatohead Posts: 10,261
    edited 2013-05-23 10:15
    @Heater, let's just do it when the time zones make sense.
  • mindrobotsmindrobots Posts: 6,506
    edited 2013-05-23 10:21
    potatohead wrote: »
    @Heater, let's just do it when the time zones make sense.

    For face-to-face meeting or for beer - I'm not sure I have a good time zone for face-to-face! :lol:
  • LoopyBytelooseLoopyByteloose Posts: 12,537
    edited 2013-05-23 10:34
    I drank myself from Boston.
    I think I nearly lost em.
    I dearly dearly do hope so.

    Now I know I am in trouble.
    My vision's seeing double.
    Crawling...
    Creeping...
    As I go..

    Sorry, no beer for me.
  • lanternfishlanternfish Posts: 366
    edited 2013-05-23 23:54
    And don't you just love the multitude of 'tech gear' that comes with fancy packaging, a CD (sometimes) and a 'manual' that doesn't tell you anything about the finer details of the device in question.

    And my BIG gripe at the moment is that many of my predecessors have kept the manuals for equipment we no longer have but the manuals for the current equipment? Gone! At least most have them have been found on manufacturers or other websites.

    If anyone wants a read of a 'how not to write a manual' have a read of a Strand 520i manual. Completely indecipherable. At least there is an abridged and slightly more readable version available.
  • LoopyBytelooseLoopyByteloose Posts: 12,537
    edited 2013-05-24 04:40
    Are you sure the manual for the new stuff really disappeared?
    It may be that it just was never included as companies have gotten away from offering CDs.

    Now they just offer the 'introductory manual' and suggest you can download the long version. Saves printing, eliminates packaging CDs, and so on.

    These days, just about everything I buy comes only with the Chinese version of the 'introductory manual'. So I have to constantly go to the internet and download the 'complete manual' and the 'introductory manual' in English.

    In sum, if you want any current manual... try on-line. You may be accusing your co-workers of absconding with something that never arrived.

    My new Canon PowerShot SX150 manuals are total train wrecks. One is very short with all the legal liability stuff and very little else; the long one is too long and too pedantic.

    I feel that they are quite fearful about consumer liability in the first, and really think that the user never saw a camera before in the second.

    And so, the users validate the idea that reading the manual's is useless... because the manual's are not informative and convienent to the general user population.
  • Heater.Heater. Posts: 21,230
    edited 2013-05-24 05:36
    Loopy,
    Now they just offer the 'introductory manual' and suggest you can download the long version. Saves printing, eliminates packaging CDs, and so on.
    With the advance of 3D printing I can see that one day you will gleefully open the box containing the latest object of desire you have purchased. The box will be empty except for a little brochure telling you how great the product is, thanking you for purchasing it, and directing you to a web page where you can down load the design files to print it yourself. And a link to the operating manual.
  • LoopyBytelooseLoopyByteloose Posts: 12,537
    edited 2013-05-24 09:21
    For anyone that has really studied Material Science, the idea that a home 3D printer could fill your every need is absurd.

    There would be no reason for metallurgy and all the processes of tempering and annealing.

    Furthermore, some materials are best carved out a billet rather that printed in layers. Manufacturing will forever work with two primary approaches: additive processes and subtractive processes.

    Camshafts and crankshafts are subtractive processes from steel billets.
  • mindrobotsmindrobots Posts: 6,506
    edited 2013-05-24 10:08
    OK, so you need a home 3-D printer and a home CNC. One addeth, one taketh away!
  • Heater.Heater. Posts: 21,230
    edited 2013-05-24 11:26
    Yes, yes, I know. I was just extrapolating your complaint about having to print a products documentation into the Star Trek realm. Who would of imagined it would happen? Already we have the likes of IKEA who expect you to build the furniture they sell you yourself. There is an on going trend to move work from the supplier to the consumer.
  • LoopyBytelooseLoopyByteloose Posts: 12,537
    edited 2013-05-25 10:57
    Taiwan has three major industries - plastics, steel, and electronics. Why do we have to do all this at home and at our own expense? Just buy what you want from Taiwan.
  • Heater.Heater. Posts: 21,230
    edited 2013-05-25 11:17
    Because intellectual property owners protected by powerful laws would rather you just paid them for using their IP for whatever design than go through all the tedious and messy business of actually making anything.
  • LoopyBytelooseLoopyByteloose Posts: 12,537
    edited 2013-05-26 02:15
    I still think that idealizing the 3D printer and/or the CNC machining is ignoring the ever important process of casting. It doesn't matter if it is steel or plastic, there are times when casting is the most economical for mass production.

    Intellectual Property has just been a way to move the goal post in the past 30 years. We have also seen the offshore national boundary extend from about 3 miles to 200 miles and beyond in the the past century or so. There is a lot of 'talk'' about 'the rule of law', but the greedy are constantly redefining property to their own advantage.
  • Heater.Heater. Posts: 21,230
    edited 2013-05-26 02:36
    Casting. Yes I love it. We were making things out of cast aluminium in school, age 15, it was a lot more fun than watching a 3D printer for hours and hours and ...I can't imagine there is a school in the world that would allow kids to do such a dangerous thing now a days.

    I think the key here is "mass production". 3D printing is more about being able to make those one off custom items or prototypes.
Sign In or Register to comment.