How to Write a Good Electronics Instructable

This Instructable was inspired mainly by my contributions over at The Clinic, which, if you haven't heard of it, is a forum thread where you can go to ask for help critiquing your projects. I typically volunteer to help out with electronics or robotics-related projects, and found myself giving some of the same repetitive advice to new authors. While there are several great "How to Write a Good Instructable" guides, ranging from this one by site founder Eric Wilhelm, to this one by veteran contributor Kiteman, to this recently featured project, I thought it might be helpful to write one specifically about electronics projects. With so many Arduino, Raspberry Pi, and RGB LED projects floating around, there are a few pointers you can follow to really help your Instructable stand out - and hopefully get featured (and maybe even win a contest, but I don't make any promises). I'm hoping this Instructable will be useful to both beginners trying to get featured for the first time, and electronics gurus who need help writing projects for a general audience.

I do want to clarify what this Instructable is not: I'm not going to re-hash general rules of thumb, like using proper grammar instead of text-message style abbreviations. If you're looking for general style and formatting advice, check out one of the guides I listed above or the Featuring Checklist. Instead, I'm going to focus on four main things that can turn a good electronics project into an awesome electronics project, that I've specifically seen people have trouble with in The Clinic:

A detailed materials list
Clear photos
Breadboard diagrams
General beginner-friendly writing style

Think I missed anything? Leave a comment below!

*Note to judges: I'm hoping this will still qualify for the Remix Contest even though it is a remix of multiple Instructables instead of just one.

Step 1: General Approach

Before going into more detail, I want to outline my general approach to writing Instructables: assume the reader is a beginner who has never seen your project before. This mindset will frame the approach for the following steps. This is useful for newbies and experienced tinkerers alike, because there are two major pitfalls you want to avoid:

Skipping over steps that seem obvious to you, because you just did the project and you have it sitting right in front of you. This can happen to both first-time and experienced writers. There might be some simple intermediate step, that you didn't think was worth documenting, that a reader could get totally hung up on. It's better to err on the side of over-documenting rather than under-documenting.
Excessive use of jargon or terminology that will confuse new users. This advice is more geared at the experienced electronics gurus. If you use a certain set of terminology every day at your job, or have been doing electronics as a hobby for 30 years, the associated language becomes second nature. It's easy to forget that it might be completely bewildering to a kid who hasn't even had a physics class yet, or an adult who took high school physics 20 years ago and doesn't remember a thing. The great thing about the maker movement is that it encourages anyone to dive in and make stuff - and you want to make your Instructable accessible to as many people as possible

Caveat: I realize that there will be some exceptions to the second point. Sometimes you might want to write an advanced DIY quadcopter project that is really only appropriate for someone who already had quadcopter-building experience, and not someone who is out to blink their first LED. This advice is intended for the big percentage of Instructables that should be accessible to beginners if written properly.

Step 2: Make a Detailed Materials List

Every electronics project should start out with a good materials list. My number one piece of advice is to provide exact links to the parts you used with quantities. Include a list of tools required to do the project - not everyone has a laser cutter or 3D printer, or even a soldering iron for that matter. Here are examples of "bad" and "good" materials lists (for a "project" I'll be using as an example in the next couple steps):

Bad Materials List

breadboard
batteries
LED
resistor
switch

Good Materials List

More generally, I've seen two recurring offenses that you should try to avoid:

Use of parts you "just had laying around" without further explanation.
Use of a single word like "resistors" or "transistors" without specifying, size, type, or quantity.

Let's take two examples in more detail: transistors and wire.

Let's start with transistors. There are over 100,000 search results for "transistor" on Digikey's website. Even a hobbyist-oriented site like SparkFun, with a much smaller selection, returns multiple results. Without more information than "transistor," there's no way for someone to know which part they need to do your project. So, you could go further and specify the type (e.g. NPN), or one step beyond that and actually specify the part number (e.g. 2N3904). I'd always recommend providing a link to where you bought the part. Navigating a vendor's website might seem like a piece of cake to you, but it can be intimidating to a beginner. Think about how many part numbers differ by just one letter or number, and how much confusion that could cause someone browsing an electronics site for the first time (for example, the L293 and L293D motor drivers, which have different product pages but share the same datasheet).

How about wire? Wire is a very common item to "just have laying around." Odds are you have stockpiles of it and didn't buy it specifically for one project. But remember - "wire" might be too vague. What kind? What gauge? Hookup wire? Speaker wire? Magnet wire? How would someone following your directions exactly know which kind to use? Don't make them guess from the pictures. Even if you didn't buy a part or a general "consumable" specifically for this project, take the extra time to look up links for where you would buy them if you needed more. For example, here's a nice 22 AWG solid-core hookup wire assortment.

The same goes for pretty much every other electronic component you can think of. Resistors, diodes, LEDs...you name it, and there are probably thousands and thousands of different kinds with different specs. Providing links might not work for everyone (for example, people in different countries, and I know some people swear by eBay for better prices), but that extra effort on your part is just one more way to make your project more accessible.

Step 3: Photos: Avoid Workbench Clutter

Good photos are key to any Instructable, not just electronics ones. There are entire groups of Instructables dedicated to taking great photos, including how to take good photos with a smartphone and how to improvise a home light booth or photo studio. I won't try to repeat all of the excellent work done there, or provide detailed advice about adjusting settings on your camera. Instead, I'll focus on the single most important thing you can do for your electronics project: clean up your work area and use a white background.

That might sound like a lot of extra work when you already have your project sitting amidst parts for 8 other projects on your desk, or on your kitchen table with last night's dishes in the background. But remember - you want to go the extra mile to make your Instructable really stand out. Messy photos won't look good, and they could make your project hard to follow. That means taking a deep breath and cleaning off your workbench or doing those dishes. The difference between acceptable photos and great photos could make the difference for that super-awesome thumbnail that make people go "whoa, that looks cool" and click on your project, or the extra push you need to win that contest, so it's well worth the effort.

My "photo area", shown in the pictures above, originally consisted of a $1 piece of white posterboard and some Scotch tape. Taping the posterboard to the wall behind the desk gives you a nice seamless background with no creases or edges visible. Eventually, I added two $15 clip-on lamps from Target with "daylight" CFL bulbs for slightly better lighting, but that's it. If you don't have the budget for a couple extra lights, try to take your pictures in a room with good ambient lighting during the day. Again, this is just my setup - there are a lot of other good Instructables for how to set up a low-budget photo area at home. You can click through the images above to see some examples of "good" and "bad" photos (by my standards, which are probably much lower than some of the true photography buffs out there - critiques welcome!).

As an added bonus, you can use image editing software to clean up your pictures and get that super-crisp, nice white background that you might see in some of the staff Instructables (I use randofo's Simple Bots projects as inspiration). No need to spend hundreds of dollars on Photoshop - GIMP is an excellent open-source image editing program that will get the job done. I'm not going to include a "GIMP tutorial" as a subset of this Instructable, but if you get stuck trying to use GIMP, leave a comment and I can try to help. Jessyratfink also has a great Basic Photo Editing Instructable that you can check out.

Step 4: Circuit Diagrams!

No matter how great your photos are, you should never rely on them to tell people how to build your circuit. That brings us to the next rule: make circuit diagrams. I've seen two common mistakes here:

Beginners will just take photos of a circuit, because they didn't know about breadboard diagrams or software available to make them.
Experts will provide circuit schematics (what you'd see in a physics or electronics textbook) but not a breadboard view, forgetting that many beginners won't know how to read a schematic.

You can certainly argue that everyone should learn how to read a schematic - and I agree that they should, eventually. There are great resources available to help you with that. But for many first-timers, schematics look like an alien language, and a breadboard diagram will be much easier to follow.

"But I don't have thousands of dollars to spend on professional circuit-diagram-making software!", or "I've never made a circuit diagram before, and I have no idea how!", you say. Don't worry - assuming you have access to a computer since you're writing an Instructable, you have a few options, none of which are very daunting to learn. See the pictures above for some examples of each:

Fritzing is a great open-source tool for creating breadboard diagrams. It has a drag-and-drop interface that lets you connect components just like if you were working with a real breadboard. It also automatically generates circuit schematics if you want to include those. I won't be writing my own Fritzing tutorial here - see their website for help getting started.
Inkscape is an open-source vector graphics program (Inkscape is to Adobe Illustrator as GIMP is to Photoshop). While it is a lot more work to manually draw diagrams yourself from scratch, sometimes I prefer it due to one flaw I see in Fritzing*.
Believe it or not, Microsoft Powerpoint works to make breadboard diagrams or schematics, since all you really need to do is draw basic shapes. I used it to make the drawings in this Arduino project and this Raspberry Pi project before I discovered Fritzing or Inkscape (drawing on top of a breadboard image copied from Fritzing).

Remember: yes, breadboard diagrams mean more work for you, especially if you were just planning on going with photos, or if you used professional CAD software to make schematics. But, your goal is to make sure many people as possible can do your project. If you want to include schematics for advanced users, great - they'll skip over the breadboard diagrams anyway. Including a breadboard diagram could make the difference between someone successfully completing your project, or being too intimidated because they don't understand how to build the circuit.

*Fritzing uses a quasi-3D view of many of the "taller" breadboard components (LEDs, transistors, potentiometers etc), which makes them obscure several adjacent rows on the breadboard (or columns, depending on how they're oriented). This makes them take up more space than they would in a pure "top down" view of the breadboard, and can make it difficult to design a tight-packed, crowded circuit. Don't get me wrong though - Fritzing is great.

Step 5: General Writing Style

This advice especially goes to all my friends out there with engineering degrees. When you use a certain set of terminology everyday at your job (or every evening/weekend if you are an experienced hobbyist), it becomes second nature. You'll use words, phrases, and acronyms without giving a second thought to the idea that people outside your profession might not know what you mean. That might work great for communicating with your colleagues, but it isn't a great approach for Instructables. The great thing about the maker movement is that it encourages anyone to get into making stuff - and "anyone" includes kids young enough that they haven't ever had a physics class (let alone an electrical engineering course), or adults who took high school physics decades ago and haven't touched it since. That means a huge part of your audience might consist of people who have zero familiarity with things you consider bread-and-butter, like adding resistance values in series or the forward voltage drop across an LED. Even if you have a detailed materials list, professional-quality photos, and super-clear step-by-step breadboard diagrams, you could still leave someone just blindly following your assembly instructions without really understanding what's going on. The writing ties it all together - and if you put in some extra effort, you can really make your Instructable great.

Does that mean you need to write a step re-explaining Ohm's Law in every single one of your projects? Of course not - if you try to explain all of the basics every single time, you'll find yourself writing an entire electrical engineering textbook from scratch. There are, however, a few things you can do:

Explain acronyms and jargon! Not everyone knows the difference between NPNs and PNPs or BJTs and FETs, or can recognize that IC you're referring to just by the model number (555 timer anyone?). See how I just violated my own rule there? Imagine how confusing this bullet looks to someone who doesn't know what any of those things are. You might say to yourself, "Hogwash! Everyone knows that IC stands for integrated circuit!" or "If they don't know, they can just Google it!" or "Really? Who hasn't heard of a 555 timer?" But remember - we're talking about how you can go above and beyond the normal call of duty for writing an Instructable. Stop to think about whether you'd know what any of those things meant if you were 12 years old, or if you mentioned them in a conversation with your grandparents at Thanksgiving dinner. Do you want to make your project accessible to as many people as possible? Then take the extra couple seconds to type "integrated circuit (IC)" instead of just "IC", or provide a link to the 555 timer's Wikipedia article. That style of writing and providing references will make your project friendlier and more approachable for beginners, who might otherwise be intimidated by the wall of acronyms and numbers they don't understand.
Give readers an idea of what concepts they should familiarize themselves with if they want to understand how your project works. Sure, you might have some people who will just blindly follow a breadboard diagram and not care what's going on inside the circuit; but you will also have people who are genuinely curious as to what's going on, and be intimidated or confused about where to start out. They might not even know what questions to ask or what they should Google. So again, you don't need to write your own page explaining Ohm's Law or what a capacitor is every time - but you could give a brief explanation and provide a helpful link: "If you want to know how the circuit works, you will need to understand voltage, current, resistance, and the equation that relates them, which is called Ohm's Law. You can read more about Ohm's Law at this great SparkFun reference." Another few extra seconds of work on your part, but a world of help to a beginner getting started on the right path.

For the record, SparkFun has a whole part of their site loaded with tutorials and guides, as does Adafruit. There are also some good Instructables references like Basic Electronics by randofo. I find that Wikipedia articles tend to be a little heavy on technical language - so while they might be a good quick reference for "what is this thing," they're not the best place for a beginner-friendly explanation. If you can't find what you're looking for right away, spend a little time Googling for a good beginner-friendly resource. Your readers will thank you.

Step 6: Additional Pointers

Here are a few additional pointers that I didn't think needed their own detailed steps:

Videos:does your project move, make noise, light up, or all three? Include a video! It's easy to embed videos with the new editor - just upload to a site like YouTube or Vimeo and click the "embed video" button up on the photo upload toolbar.
Code: does your project involve code for the Arduino, Raspberry Pi, or something else? Make sure you include it! For small files, you can paste the text directly into your Instructable for people to copy and paste. For larger files, you can attach them to a step (use the paperclip button on the top toolbar).
CAD files: did you 3D print, laser cut, or CNC mill something? How about making your own printed circuit board (PCB)? Don't make people reproduce all your work - provide the files for download. You can host them on the Instructable, and/or an external site specifically for CAD files like Thingiverse.

Step 7: Summary

Ok, so that got a little long. Here's a recap of the main points.

Make a detailed materials list with links to the exact parts you used.
Take good photos on a clean white background.
Make breadboard diagrams to show how to assemble your circuit.
Use a beginner friendly writing style and provide links to helpful resources.

Questions or suggestions? Want to know how this advice would apply specifically to your project? Leave a comment below or head over to The Clinic for more help. Thanks for reading!