Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
Do you mean descriptions of the electronics?

Yes. Don't explain LEDs, why LEDs need current limiting resistors, how poteniometers and sensors work, how DACs, ADCs, shift registers, RS232, I²C, SPI, ... work, what pull-up and pull-downs do. That has been explained often enough and could be done by simply linking to good resources. Wikipedia might be good a candidate. I hoped to find that basic stuff at https://www.raspberrypi.org/documentation/, but unfortunately, they seem to have omitted that part.

I'm hoping to make each element self-contained

Of course, that's quite the opposite of omitting old content. But a really self-contained element would perhaps have to start with basic electronics, explaining voltage, current, resistors, and so on. You need to set a lower limit at what you want to explain. You don't want to start at quantum physics to explain electrons interacting with each other and other matter.

My idea was to raise that minumum level of knowledge from "minimal electronics" (lamp, switch, battery) to "familiar with microcontroller related hardware and protocols". That avoids a lot of work for you by not having to explain the basic stuff over and over again. And it would avoid a lot of work for the experienced reader by not having to skip over the basic stuff over and over again. Adding a few explaining links to each element for the basics would still allow readers at the "minimal electronics" level to understand what happens.

self-contained with a desc, the code, breadboard layouts so that a user can literally copy/paste

Obviously missing here is a circuit diagram. That's much more important than a breadboard layout. Yes, it could be reverse engineered from the breadboard layout. But a (good) circuit diagram is much clearer than a layout.

And if you raise the knowledge level to "familiar with microcontroller related hardware", you can omit the breadboard layout. It's obvious from the circuit diagram how to connect the hardware. And it allows to see some magic happen, teaching some good lessons. Just copying breadboards does not help to understand electronics. It can be a first step, like training wheels. But at some point, you remove the training wheels.

What's your intention? You want to explain how to use perl (your modules) on a Raspi. So that should be the primary content, not electronics. Using a nice breadboard example for connecting a LED and a potentiometer is ok. Adding one more example to the existing two million does not hurt. But shortly after that, stop detailing everything.

There is a limit for the number of components on a breadboard. Yes, you can build an entire 8-bit combuter on breadboards, but that does not mean that you should do that. I would avoid putting more than about 50 pins on a breadboard. Breadboards tend to have loose connections, especially when you move them, and when the contact springs wear out. They add a lot of parasitic capacitance due to the way they are constructed. And of course, you can't use SMD parts without adapters. Perfboards don't have these problems, but of course, reusing them is harder. They tend to loose some pads when unsoldering parts.

Alexander

--
Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)

In reply to Re^3: Contemplating a documentation series for my Raspberry Pi work by afoken
in thread Contemplating a documentation series for my Raspberry Pi work by stevieb

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others romping around the Monastery: (4)
As of 2024-03-28 16:57 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found