Creating Great Guides for the Adafruit Learning System

Transcription

1 Creating Great Guides for the Adafruit Learning System Created by Mike Barela Last updated on :09:38 PM UTC

2 Guide Contents Guide Contents The Guide Style Guide Writing Guides for the Adafruit Learning System Refer Back Here, Deja Vu Points of View Using Images Sourcing Images When Searching the Internet License Information Captions Great Pictures and Their Use Photography Single Pictures Multiple Pictures Depicting One Thought Animated GIFs File Parameters Setting Up and Filming Compelling Animated GIF Content Inserting an Animated GIF inside a Guide Recording your Screen (Mac) Youtube Videos Where Do You Put Video? Youtube Videos Embedding the Youtube Video Link Your Perfect Frizing Diagram Intro to Fritzing Download and Install Install the Adafruit Parts Library Using Fritzing Best Practices - Creating Great Fritzing Diagrams Best Practices - Parts Layout Best Practices - Wiring Best Practices - Curved vs. Straight Wires Best Practice - Connections Best Practices - Images and File Handling Aligning Parts Exporting Your Fritzing Diagram Pre-Flight Check Data and Image Files Save Those Files! Guides using CircuitPython Where does your code go? Link to the Welcome to CircuitPython! Guide Link to Installing Mu Using Internal (GitHub.com/Adafruit) Libraries Library Use Commenting Your Code Naming your Python Files Contributing Your Code Adafruit Industries Page 2 of 43

3 If you are an Adafruit team member If You are a Contributing Author Placing Code in the Guide Guides using MakeCode Where does your code go? Link to the MakeCode Guide Writing Good MakeCode Extensions Placing A Link to the Code in the Guide Adding the Picture of the Code Guides using the Arduino IDE Where does your code go? Link to the Arduino Guide Using Internal (GitHub.com/Adafruit) Libraries Using Libraries Setup for Specific Boards Commenting Your Code Naming your Code Files Creating New Libraries Contributing Your Code If you are an Adafruit team member If You are a Contributing Author Placing Code in the Guide Explaining How the Code Works Bundling Your Resources Within a Guide How to Other Details Checklist Before Launch Check Page Settings Check the Guide Settings page Check the Featured Products Page Page One Considerations For Project Guides: Guide Body Checks Code and Other File in GitHub For MakeCode The Moderation Process The Initial Moderation Final Moderation When Your Guide is Live How can I tell? Great Way to Tell if Published For Sure Blogging and Social Media What Happens after a Blog Post? Why? Metrics? Metrics! Adafruit Industries Page 3 of 43

4 The Guide Style Guide Writing Guides for the Adafruit Learning System This guide is the second in the series on the ALS Academy, with the first being Creating Guides for the Adafruit Learning System ( which walks you around the various tools available for writing guides. You should read that guide first and you can go back to it as needed. It is suggested that to learn about the functionality in the Learning System that you first read the guide "Creating Guides for the Adafruit Learning System" This guide focuses more on providing a template for how to write a guide in the style Adafruit is looking for. Just as a term paper or blog post has many ways in which it can be formatted, a teacher or a site may want things to have a certain look and feel. The guidance here will blend your material with that already in the Adafruit Learning System and become part of a resource that helps people every day in using Adafruit products and in general education and learning. Refer Back Here, Deja Vu Do make sure you refer back to this guide when you have a question as to what to do. Use the guide checklist to be sure a guide is done before putting it in moderation. Have your video and code ready for moderators to add to the Adafruit repositories if you are an independent writer. We all get rusty, you can come back to remember the finer points of doing some of the items and best practices. And, I hate to say it: try never to jump the gun in getting a guide out when it is not ready. We all hurry to get things done, especially Wednesday afternoons. Guides and subsequent blogging are things best not rushed - usually they can wait until people lay eyes on them and they are in the format Adafruit management wants for publication. Points of View Use "I" when talking about individual actions "I clicked on this button" "I soldered this thing" Use "we" when talking about stuff we do as a group "We publish on github" "We have a contribution process" It's ok to mix em, they mean different things Adafruit Industries Page 4 of 43

5 Using Images Pictures are a fundamental part of all guides. "A picture is worth a thousand words" is fairly accurate. You should take a picture where it would: 1. Show your project working or in a finished state 2. Show how the project was created/assembled Sourcing Images The best pictures are usually taken yourself. This ensures they are the author's property and can be used freely. If you need to use images from elsewhere, you must be very careful: Most pictures on the Internet are not "free to use" Many pictures licensed for creative commons require attribution. You must not use any picture where it is unclear as to the source or use in a guide. When Searching the Internet Again, it is not suggested that you use the Internet for pictures/drawings/etc. But if you must, here are some rules for doing so: 1. Consider Wikipedia ( / Wikimedia Commons ( Wikipedia does not allow images that do not comply without Free to Use, Creative Commons, or past copyright. If sourcing from Wikipedia or Wikimedia Commons (the image repository), you MUST adhere to the image rules for use Please refer to the Wikimedia Commons Reuse Page ( to learn about how to reuse their images properly. 2. Pexels - refer to the Pexel License Page ( 3. Pixabay - see their info on public domain images ( A useful database for looking up intellectual property release requirements for pictures is ( There is a difference between editorial and commercial use. Model- and Property Releases are particularly important for commercial applications. If you are i.e. showing an image on your blog, it is non-commercial, editorial usage ( In general, no release is required for such applications. Commercial use is loosely defined as all sorts of businesses, where you are actually selling something, or if you use images for advertising purposes. License Information Needs to be expanded 1. CC0 Adafruit Industries Page 5 of 43

6 2. CC BY-SA Captions Many fair use rules in the reuse require the picture be captioned. It may be a credit to the author. It may also be what license you are using the photo. Be sure you caption the picture appropriately. The Adafruit Learning System allows any still image to have a caption. Right click the image, select Add/edit Caption, and type it in. The caption will appear as text in a black bar at the bottom of the image. Adafruit Industries Page 6 of 43

7 Great Pictures and Their Use Photography See the new guide Guide to Project Photography ( Single Pictures Single pictures are placed in a guide with the MEDIA button at the bottom of the page. Multiple Pictures Depicting One Thought For pictures used for one series of steps, like assembly, use the SIDE2 button. With SIDE2, you can include several pictures on the left and text on the right explaining what's happening. Like an instructional video but a lot less bandwidth and complexity (people have their own speed following guides). Please do not put more than 4 pictures in a SIDE2! They get hard to follow. If you need more, select a new Side2 to put below the previous one. Also, please do not use TABLE for multiple pictures. It may have bugs so we're looking to avoid it's use for now. Adafruit Industries Page 7 of 43

8 Animated GIFs Animated GIFs have been around a long time in Internet years. It was a format for tacky MySpace icons etc. But it's made a comeback for very short video clips placed where a static picture might have been used. The website ezgif.com ( allows you to convert short video clips to Animated GIF. The app site allows import, render, and edit. If your vid is rotated 90 or 180 degrees, it can fix it. The cropping is only via a resolution change but it is possible (try to crop in filming). There are probably other websites but not all are 100% innocent - some have download buttons that are really ads near the real download button or may have bad popups. On a Mac, there is an open source program, GIFski ( coauthored by the Awesome list guy, that is supposedly good. Some video editing programs will also output to animated GIF as an option. File Parameters Here are the parameters you should consider for animated GIFs in the Adafruit Learning System: Guide Settings Thumbnail: Max size 800 by 600 (try to get a 4:3 aspect ratio), no larger than 7 megabytes in size. Animated GIFs in the guide itself: The same as regular pictures, try for a 4:3 horizontal aspect ratio, 100 megabytes max but try to keep it under 10 MB. When the guide exitor sees an animated GIF, it'll put the words Animated GIF in a small black box to the upper left of the picture as an indicator. Setting Up and Filming Compelling Animated GIF Content When a guide is in the moderation process, any Animated GIFs will be reviewed. All GIFs should be a workable part of the guide. You don't need many, most posts may only have one, perhaps none. You should set up a GIF shoot similar to a Youtube or other video shoot: Set up for filming the content If a background is used, ensure it's appropriate (white, black, etc.) Ensure aspect ratio of recorder, 4:3 best Ensure resolution isn't too small (320 width is too small, 600 is good for GIF) The length of most clips is only 2-4 seconds GIFs loop so make sure there is not an abrupt transition between start and end Most videos have been filmed on a table. But be creative. You can take something like Blu-tack to paste a board to your monitor with code next to it and film a GIF, works well. The goal is a compelling, informative, good looking demo clip. Inserting an Animated GIF inside a Guide As with a picture (JPG, PNG, etc.) use the Media icon to specify what file you want to put in your guide. Adafruit Industries Page 8 of 43

9 Recording your Screen (Mac) If you want to record complex actions on your computer's screen, or include real-time readouts into your guide (a serial plotter perhaps?), you'll need an application which records GIFs. If you're running macos, you already have a screen recorder pre-installed but it's hidden within Quicktime Player. To access the screen recorder within Quicktime Player, open Quicktime and click File -> New Screen Recording. Quicktime will close to your menubar, it'll look like a circle with a square. Click it to stop the recording and bring up the finished file. Quicktime export default is a.mov file. You can use the websites listed above to convert it into a GIF. We also like an application called Kap ( It sits in your menubar and can record your screen at a moment's notice. A floating window with a red record button will pop up. Once you click the red button, you'll be given a draggable window (stretch this to fit your recording area) and a button labeled start recording. Click this button when you have everything ready. Clicking the Kap icon on your menubar will bring up a small tooltip which lets you adjust the aspect ratio, screen dimensions and microphone settings (you can screencast from Kap). After recording, Kap gives you some nice options - you can select the recording framerate (60FPS or 15FPS) and trim the recording from within the preview. When you're all set, click GIF and Kap will export the recording and convert it into a GIF. Adafruit Industries Page 9 of 43

10 Adafruit Industries Page 10 of 43

11 Youtube Videos If a video would convey information about building or using a project, then by all means do consider a video. Where Do You Put Video? The picture that goes in the Guide Settings can be either a still picture or a smallish animated GIF. If video really shows your project off, consider an animated GIF. Making good GIFs is discussed on another page of this guide. In the body of the guide, a video often works well on the first/overview page, right under the page name. This is not required but is a good touch if the video captures the essence of the project. Generally during the build process, assembly is shown with still pictures. You can put a video in anywhere in the body of the guide, the video should be appropriate to the placement. Don't overwork yourself with a 1 hour build video, it's too much for an ALS guide. Many guides will be printed out as PDFs which will not show video, so all build steps should be pictures and text. Demonstrating the finished product is good for a video and it can often be the same as the video you put on the Overview page. Youtube Videos Youtube is a great way to add video that lasts more than a handful of seconds. Videos should be importable by Youtube and be edited as to the content & sound, if needed. Not all video needs editing if you're careful with the shoot. All video should be a good shot without noisy distractions or outtakes. Internally at Adafruit, authors can upload to the Adafruit Youtube Channel. For folks outside Adafruit, you should work with the person designated to assist you with your guide on getting video to put in your guide. This may involve Google Drive, Dropbox, etc. but some videos can be small enough for . The Adafruit person will take the URL of the video, usually private in the Adafruit repository, and send it back to the guide author to imbed in the guide in the correct place. Embedding the Youtube Video Link On the list of options at the bottom of the page you want to embed the video, click the embed icon. Then paste the address of the Youtube video into the Embed box that pops up. Click Save. It'll look funny in edit mode but it's ok, the Learn engin knows what to do when showing it to a user reading it. Adafruit Industries Page 11 of 43

12 See the Youtube link in the grey box - that's perfectly fine in guide edit mode. In user viewing mode or Preview mode it looks like this: If you click the SHOW EMBEDDED CONTENT the video will show. That is the privacy setting you might have on your browser (mine is Chrome). No worries, Adafruit is respecting your wishes re. showing the content when you have do not track in the browser. Adafruit Industries Page 12 of 43

13 Your Perfect Frizing Diagram Intro to Fritzing What is Fritzing, a German holiday? It is actually a pretty powerful open source program which aspires to the greatness of Eagle and KiCad. But don't fear, most often we use it for the thing it does very, very well: Make diagrams of electrical projects. Fritzing has a plethora of built in parts diagrams. With the addition of Adafruit's parts library and a bit of know-how, you can make project drawings that nearly any user can understand. Even if you've used Fritzing, there are some tricks and best practices here that you should know to ensure you meet the exacting eye of Limor. Let's dig in. Download and Install You can find Fritzing at Fritzing.org ( Download the latest version ( for Windows, Mac, and/or Linux and read the notes for Mac & Linux. Yes, it is marked beta software - it's been that way for YEARS, we live with it and its little quirks (as with nearly all software). If you have an older version, updating does make sense and is recommended. Install the Adafruit Parts Library Please read this guide on the learning system ( on how to add all of the Adafruit Fritzing parts to your Fritzing installation. The library import method has changed over time so see the guide if it's been awhile. When you quit Fritzing, it will ask if you want to save your imported libraries. Say yes. Using Fritzing A decent number of Fritzing diagrams start with a breadboard and place parts on the breadboard and possibly around it. When you select the Menu -> New item, the default is to give you a breadboard. There is a comprehensive tutorial online on the Fritzing site ( for learning the basics. Adafruit Industries Page 13 of 43

14 You can pick the many of the program's basics by just practicing. Grab a component and drag it out to the breadboard. When the pins align between the breadboard (or any part) and the part you have, the pins turn green. Green lets you know the two parts are aligned and connect electrically. This is a great thing - remember this. Learn either between the tutorials and/or through building some diagrams. Please browse some tutorials that have diagrams in the Adafruit Learning System (keyword: Fritzing) to see how others may have done their diagrams. Best Practices - Creating Great Fritzing Diagrams Following the hints below, you should get decent Fritzing diagrams and subsequent pictures. If you're unsure about things, ask (then document here so others can read about it). Best Practices - Parts Layout You will want the final picture of the drawing to be close to a 4:3 landscape oriented snapshot as possible for best results in the Learning System. See the diagram above - the parts were laid out more horizontally rather than vertically, to the point that the Crickit + CPX were rotated which is ok! Don't worry about the Fritzing logo during layout, see below under images. Best Practices - Wiring Every diagram has some wires connecting things. Here is how to get the best results. Wire Color: Select appropriate colors for all wires. Positive power is usually red, ground is black (even though the breadboard tends to have blue printed on it). Other wires should be of colors that help distinguish what is being connected. Right click on a wire to change its color. Wire Routing: Try not to cross two wires of the same color as it might be difficult to the less experienced maker to Adafruit Industries Page 14 of 43

15 know they do not connect at crossings. Do not get too many wires crowded to it is difficult to make out which wire connects to which connection. Think about how to route wires and don't be afraid of moving them during the process. Joints: a straight wire can be bent at any point along it by grabbing it with the mouse and pulling.this will create angular bends which can be fine but see below on curved bends. Best Practices - Curved vs. Straight Wires On older Fritzing diagrams, all of the wires have angular bends in them. There is an option now to have angled bends at bend points or to have curved bends. The curves look smooth as they are rendered as Bézier curves. Go to Edit -> Preferences And select the Breadboard View tab. There the text reads: Curved wires bend depending on points you select ala straight wires. But the curves can be either up or down depending on how you move the curve point. You might need more than one bend point to get things in the right direction or you might have to delete a failed wire and try again. It is definitely more an art than straight wires. Here again is a diagram that uses curved wires: Adafruit Industries Page 15 of 43

16 The speaker wires come out from the part a bit. Conventional straight wires connect those "part wires" to Crickit speaker terminals (which are now light green). The servo wires are curved. They connect to the servo such that you can see each wire. Hint: For servos, Ladyada suggests going from Crickit to the Servo rather than from the servo wire to the Crickit pin, it makes it easier to wire and I agree having done it both ways). The battery box has long "part wires". Two curved wires come from the power plug to meet the part. Since the ends are tinned on the battery box part, I put two extra straight wires on to cover the tined leads as in reality the tinned ends would go in the connector but doing so would not fit the drawing esthetic or the 4:3 ratio. Things like motors almost always have long wires and are good for curvy lines as are wires with alligator clips. Below is one of Limor's more recent diagrams. See how she's laid things out? Adafruit Industries Page 16 of 43

17 Best Practice - Connections Try to ensure point to point connections end in a green (rather than a pink) color. This is how Fritzing indicates an electrical connection. It's a small point but if the user was doing this to make a circuit board, that is the type of connection it should have - it shows you put extra in the diagram. Here are two pictures of Crickit and CPX - the one on the left is not aligned, the one on the right is, note the green under certain pads, they are "connected" when green. IT IS NOT EASY TO DO sometimes - moving the CPX on top of Crickit is very hit or miss. If you put the CPX on top close and then click Crickit and move it slightly, I got it to lock green, perhaps I was lucky. See all the pink pads around Crickit's edges. You'll want them to turn green also when you make connections to those pads. Adafruit Industries Page 17 of 43

18 Best Practices - Images and File Handling The Fritzing logo: the logo should remain on all completed diagrams. When a diagram is exported, Fritzing places the logo in the lower right. If you decide to crop the Fritzing image, copy or move the logo so it stays in the lower right if at all possible, along the bottom if not. Not all diagrams have to have additional work. I put text identifying things for Getting Started with Adafruit Trinket but in guides it is usually obvious. Less can be more - not putting a hard rule in here (yet). To add text inside Fritzing go to Edit -> Add Note to make an orange-colored sticky note. It is good to put some notation like Limor did above if a component is not obvious as to function - a user might not know the difference between the solenoid and relay icons. Aligning Parts Sometimes, a part won't align. This happens if the part, or other parts, do not correctly line up with the grid: Adafruit Industries Page 18 of 43

19 Don't fear - we can line up the part perfectly by bypassing the align-to-grid feature and manually positioning it. Disable the alignment by unchecking: View - > Align to Grid. Then, move the part by using the arrow keys on your keyboard or your mouse. After it's positioned perfectly, re-enable the Align to Grid setting. You can also lock the part to make sure it doesn't move around by left-clicking and checking the Lock Part option. Exporting Your Fritzing Diagram Done wiring up your Fritzing diagram? Ready to share it with the world? Believe it or not, this is arguably an important part of the process. Pre-Flight Check Think of hitting the export button as clicking the shutter on a camera. You want to make sure the first image you take it perfect. Let's make sure it is. Adafruit Industries Page 19 of 43

20 Here's a general Pre-Flight Fritzing Check. After building your circuit, make sure you go through this list before clicking that shiny Export button. 1. Are all parts connected? 1. Connections should be green 2. Do all components get power? 1. Check the connection from your board to the power rails 2. Check the connection between the power rails to each component 3. Polarity check 1. Some parts are not symmetrical (i.e: ICs, transistors, capacitors, batteries, and LEDs). These parts have a specific orientation to follow, and orienting them incorrectly can cause the circuit not to work (or worse) when reproduced by an eager learn-guide reader. 4. Reproduction Check: Can someone reading the learn guide reproduce your work? 1. If you're producing the Fritzing diagram from a project on your desk (on a physical breadboard or a PCB), cross-verify the physical layout with your fritzing diagram. 2. Go through each wire by slowly verifying the physical layout: "this wire goes from Feather Pin 16 to the SCL Pin" and then checking the layout on your computer screen. 3. If your Fritzing Diagram doesn't work, assume a person can't go through the learn guide. It's easier to handle this than feedback. Data and Image Files Fritzing stores the data for its files in a file with the extension.fzz. You should save your work products fairly often. There is an undo feature Edit -> Undo if you make a mistake. But there are times when you might have an intermediate work product or something you don't want to have to recreate so you save the file. Any computer can crash, save your files. The Adafruit Learning System does not have a method to display.fzz files. Normally, you will use Fritzing to create an image file of your final result. From the menu select File -> Export -> As Image -> and you should select PNG or JPG. This will save the file in either the JPEG or Portable Network Graphics format. Both can be imported to ALS, no worries. Adafruit Industries Page 20 of 43

21 Sometimes the graphics file needs to be tweaked in an image editing program. Maybe add information that Fritzing is unable to put in the diagram. Maybe there is a 3x AAA battery pack in the library but not a 3x AA pack - just erase an A. Save Those Files! If you make a Fritzing diagram and have the.fzz file, we need to save it in the guide for possible later use. How & why? See the page Bundling Your Resources Within a Guide ( about this. Adafruit Industries Page 21 of 43

22 Guides using CircuitPython For an exemplar (example guide) for a CircuitPython project guide, see Guides containing CircuitPython code should consider following this format to some degree: Where does your code go? Code is often on a page called Code or CircuitPython This lets folks know where to go for the code Link to the Welcome to CircuitPython! Guide Put in text similar to the following: Are you new to using CircuitPython? No worries, there is a full getting started guide here ( where the link is ( Folks may be new to CircuitPython, so this will get them started. Link to Installing Mu Put in something to the effect: Adafruit suggests using the Mu editor to edit your code and have an interactive REPL in CircuitPython. You can learn about Mu and installation in this tutorial ( The link is ( Using Internal (GitHub.com/Adafruit) Libraries If you use an externally developed CircuitPython library in your learn guide, we advise against that. Instead, select and use an Adafruit-created library. You can find these on our GitHub ( We fund the creation of libraries, provide engineering support to people using them (you) since they're our creations, they're updated often, and they won't get abandoned/go down/get deleted. Having trouble with an Adafruit-created CircuitPython library? Want to do something but the feature is not implemented? You can get in contact with our learn support immediately by ing LearnLiaisons@Adafruit.com If you're using an externally developed (non-adafruit) library on your project and don't know of an alternative, hop on the discord or LearnLiaisons@Adafruit.com and we'll find you an alternative right away. Library Use If you use libraries that are not baked (frozen actually) into CircuitPython, you'll need to help the user load them into the /lib folder. Adafruit Industries Page 22 of 43

23 Put something like this in your tutorial is using a library: You can learn about installing the adafruit_motor library in the CircuitPython Essentials Guide on CircuitPlayground Libraries ( It is easiest to install the whole library package. Commenting Your Code There should be comments at the top to let the user know what the code goes to, re. your guide. Also something like this: Open Source Software, MIT License, support Adafruit OSS by shopping at adafruit.com In the body of the code, please put comments for major sections of code. This includes: Sections that set up sections on a board, such as switches, buttons, NeoPixels, servos, etc. Definitions - what the definition is going to do Important variables the user may want to change Any major code sections For the variables, something like: CAPTOUCH_THRESHOLD = 500 # change lower for more sensitive touch servo_1.angle = 90 # start servo at 90 degree point We want our users to be able to learn from our code. You do not have to code nearly every line but comments are often good to help in key places. Naming your Python Files It is currently an Adafruit standard that the code should be called code.py You can encourage users to save the file on their hard or flash drive to something more descriptive. But when copied from the user's computer to the CircuitPython compatible board, it should be code.py and not main.py, code.txt, or main.txt even though those are allowed (currently). Contributing Your Code Your code should be fully functional when the guide is ready for moderation. If you are an Adafruit team member Put the code in the Adafruit GitHub repo and do a Pull Request. This will set things up so the Travis-CI linting program will check things. Be sure Travis has given your code a pass. It takes several minutes, you'll have to wait. Ask another staffer to review your pull request If You are a Contributing Author Let LearnMod know you have your code ready. Send your code and any videos you want for Youtube ready for processing. Let us know where the code goes if necessary but it should be obvious for standard guides. The moderator will put the code into the Adafruit GitHub and send a Pull Request. This will trigger the Travis-CI Adafruit Industries Page 23 of 43

24 module to check the code for possible issues (called linting by some). If Travis finds issues, correct your code and send back. When the code is in GitHub and passing Travis, you can put a link to the code per the section below. Placing Code in the Guide The current method to put GitHub based code into your guide is as follows: Use the Embed icon at the bottom of the page: Type in the URL of the folder containing your code into the box. In a guide being edited, the embed will look like this: When your guide is in Preview or Live, it will look like this: You can use the Preview link on the right side to see that the code is Embedded correctly. Adafruit Industries Page 24 of 43

25 That's it. If you see there is an issue in this process, either tweak it yourself or let LearnMod know via . Adafruit Industries Page 25 of 43

26 Guides using MakeCode An exemplar (good example) of a project-based MakeCode oriented guide is at Guides containing CircuitPython code should consider following this format to some degree: Where does your code go? Code is often on a page called Code or MakeCode This lets folks know where to go for the code Link to the MakeCode Guide Put in text similar to the following: Are you new to using MakeCode? No worries, there is a full getting started guide here ( where the link is ( For the Circuit Playground Express, there is another guide also: MakeCode for Circuit Playground Express ( Folks may be new to MakeCode, so this will get them started. Writing Good MakeCode Most MakeCode folks will be beginners. Try to make your programs relatively straightforward. Try to not use too many variables. Often there are oval values that can be put in where a variable can be so you can combine things. Can be better written as Adafruit Industries Page 26 of 43

27 Try to avoid using functions unless it really helps to make a program clearer. Extensions If you use extensions as in Crickit or other extension code, explain to the user where to find the extension and what the extension block looks like when installed. Here is the guide that explains adding the Crickit extensions for CPX: ( Placing A Link to the Code in the Guide You put your code into the guide as follows: 1. Share your code on the MakeCode website. Adafruit Industries Page 27 of 43

28 At this time don't use the MakeCode Embed link, lower lefty in that dialog. 2. Put an embedded link to the MakeCode website where you have your code Use the Button icon at the bottom of the page: Then put a name for the button and insert the sharing link for your MakeCode on the MakeCode website: Then you have a green button for downloading your code. Adafruit Industries Page 28 of 43

29 Adding the Picture of the Code Take a screenshot of the MakeCode, edit if needed, and add as a standard picture via the Media icon. If the code seems small, just the code is ok, especially for large programs / programs with many modules. Adafruit Industries Page 29 of 43

30 The code should be clear enough in the guide so a person looking either at a screen or a PDF printout can replicate the code in the MakeCode editor. Adafruit Industries Page 30 of 43

31 Guides using the Arduino IDE A good exemplar (example guide) for Arduino is but use a parts list at the bottom for all parts The Arduino IDE is the most complicated software we might steer a customer to use in a guide (at least until we go into FPGAs!). The instructions for using the Arduino IDE well will take up more room in your guide but it is worth it to ensure users are able to get all the pieces to complete the guide successfully. Guides containing Arduino code should consider following this format to some degree: Where does your code go? Code is often on a page called Code This lets folks know where to go for the code. It's not a hard and fast rule. Link to the Arduino Guide Put in text similar to the following: Are you new to using Arduino? No worries, you can get started using our series of guides on Getting Started with Arduino ( where the link is Getting Started with Arduino ( Folks may be new to the Arduino ecosphere, so this will get them started. Using Internal (GitHub.com/Adafruit) Libraries If you use an externally developed Arduino library in your learn guide, we advise against that. Instead, select and use an Adafruit-created library. You can find these on our GitHub ( We fund the creation of libraries, provide engineering support to people using them (you) since they're our creations, they're updated often, and they won't get abandoned/go down/get deleted. Having trouble with an Adafruit-created Arduino library? Want to do something but the feature is not implemented? You can get in contact with our learn support immediately by ing LearnLiaisons@Adafruit.com If you're using an externally developed (non-adafruit) library on your project and don't know of an alternative, hop on the discord or LearnLiaisons@Adafruit.com and we'll find you an alternative right away. Using Libraries If your Arduino code uses libraries, you should link to the Adafruit guide on using libraries to help them get things installed. Use text like: This sketch uses the Adafruit xxxxxx library. You can learn more about Arduino libraries by reading this guide from Adafruit Industries Page 31 of 43

32 Adafruit ( ( Setup for Specific Boards Guides on specific microcontroller boards most often have a section which explains what to do to get Arduino going with that board. You can link to those instructions in the guide or mirror the page if it is contained to one page. For example, for Arduino on Circuit Playground Express (CPX), the guide to the CPX is at ( The Arduino page in that guide is at ( You can use Mirror to put that page into your guide if appropriate: If the board guide isn't such that you can mirror a page, feel free to use text from other guides to get your guide up to the level that novices can get things set up. Commenting Your Code There should be comments at the top to let the user know what the code goes to, re. your guide. Also something like this: Open Source Software, MIT License, support Adafruit OSS by shopping at adafruit.com In the body of the code, please put comments for major sections of code. This includes: Adafruit Industries Page 32 of 43

33 When including libraries, maybe a comment on what the library does Sections that set up sections on a board, such as switches, buttons, NeoPixels, servos, etc. Functions - what does the function do? Important variables the user may want to change Any major code sections For the variables, something like: #define CAPTOUCH_THRESHOLD = 500 // change lower for more sensitive touch uint8_t delay_between_samples = 5; // change is sample rate should change servo.angle = 90; // start servo at 90 degree point We want our users to be able to learn from our code. You do not have to code nearly every line but comments are often good to help in key places. Naming your Code Files For Arduino, there is no standard naming convention other than the ones Arduino sets, re. code files have an.ino filename extension, header files.h. Creating New Libraries If you are going to write a new library, seek guidance beforehand from Adafruit. Perhaps that should be a new section or a new Adafruit guide. Contributing Your Code Your code should be fully functional when the guide is ready for moderation. If you are an Adafruit team member Put the code in the Adafruit GitHub repo and do a Pull Request. Ask another staffer to review your pull request If You are a Contributing Author Let LearnMod know you have your code ready. Send your code and any videos you want for Youtube ready for processing. Let us know where the code goes if necessary but it should be obvious for standard guides. The moderator will put the code into the Adafruit GitHub and send a Pull Request. When the code is in GitHub, you can put a link to the code per the section below. Placing Code in the Guide The current method to put GitHub based code into your guide is as follows: Use the Embed icon at the bottom of the page: Copy in the link to the code from GitHub: Adafruit Industries Page 33 of 43

34 The embed link will look like this while in editing mode: If you click the Preview link in the upper right of the screen, you should see a nicer display of the code pulled automatically from GitHub and displayed in the page: Adafruit Industries Page 34 of 43

35 If you don't see your code all nice & neat, look to see if the link is incorrect. That's it. If you see there is an issue in this process, either tweak it yourself or let LearnMod know via . Explaining How the Code Works While not a requirement, it is good to put some text after the code block explaining how you accomplished writing the code for your project. Use the code font. The text might look something like this: The program loops several times collecting samples. Change the variable delay_between_samples from the default 5 to the number of samples you would like to take. Good comments in the code can help the user figure out the code, lessening the explanation that might be done in the guide. Adafruit Industries Page 35 of 43

36 Bundling Your Resources Within a Guide A newer, but important part of the guide procedure is to capture the media files and other digital materials that went into making a guide so the guide can be edited at a future date. As discussed in the Fritzing page, Fritzing saves a file with the diagram in a file ending with.fzz. This should be with the guide for folks down the road. Other files like if you used PowerPoint to do a diagram or others can be put with the guide also. How to At the end of your guide, put a page called Resources. Do not mark the page as published (as it won't ever be published externally). Place the files on the page as Embedded files. Files will show up as green boxes. The system will have the file saved and the file will be uploaded to someone pressing the green box button. Other Details Feel free to add any text in this page that would help an Adafruit employee 100 years in the future understand how your guide was done and what they might need to tweak it. Adafruit Industries Page 36 of 43

37 Checklist Before Launch Check Page Settings Is each page out of Draft? Are pages organized in the correct order? Keep page names somewhat short, 1-3 words so they don't wrap For each page: Check Page Settings for the "permalink", if you rename a page the permalink (URL) doesnt change so you may need to update these to match Check the Guide Settings page Is the title of the guide explanatory yet less than 10 words long? aim for about 3-6 words Is the short-url matched to the title? If you change one it doesn't change the other. separate words with '-' The short url is also a good place to put Search Engine Optimization (SEO) words since search engines prioritize the URL. However, still try to keep it under 10 words We have redirection capability but try to avoid changing the URL once it has been set and the guide is live. Redireciton doesnt always work perfectly, and shouldn't be relied on! Adafruit Industries Page 37 of 43

38 Check the Author & Contributors The main permalink should be the title and be clear. If it isn't, it can be changed. Check the 3 categories for the product are checked off. Are they correct? Sometimes guides change so categories need to be adjusted. Guide type should be correct: Project, Tutorial, or Product. Most guide Skill Level is at beginner but there are exceptions. Don't change Search Rank unless you know what it does. You can pick up to 3 categories only. It must have one category checked. Check the three most applicable ones. Check the Featured Products Page Is everything that is in the guide in the Featured Products page? Aim for 2-5 products per guide If there's more than 5, put them in order of adafruit/price/functionality. Adafruit made items first, most expensive/key parts next, then variants of parts go last E.g. the Metro M0 goes first, and if there's a lot of different LEDs put those last. Adafruit Industries Page 38 of 43

39 Page One Considerations Is the page named Overview? If not, should it be? For Project Guides: Is the project parts list at the bottom of the Overview/Page 1 page? Parts SHOULD be both in Featured Products (to the right side of the page) and in a Parts List format. Adafruit Industries Page 39 of 43

40 Guide Body Checks Page has a clear title Page content is not too short or too long. Long pages should be slit, short pages combined. Pictures are good. Build uses Side2 for pictures left next to text right. Arduino and CircuitPython code in GitHub with a correct link to repository? Videos are ok. Code and Other File in GitHub CircuitPython and Arduino code should be placed in the Adafruit GitHub account, usually under ( Unless there is a reason, the main program(s) should be in GitHub. Explanation code snippets can be in the guide, though, using the code block available at the bottom of the edit page. To get the GitHub code into the guide, embed the URL to the source code file (for example code.py or myprogram.ino) into the guide. Use Preview to check that the Learning System found the code and displays it as a nice block. If the guide has wav files or other sharable media, these should be in the GitHub repository also. Link to the files from there. If you have a group of files, you can ZIP them into a bundle. Then it makes it easy to use the Button tool to point to the ZIP file to retrieve the files. For MakeCode Embed the link to the MakeCode sharing link and include a screenshot of the code both. MakeCode doesn't go into GitHub although it is likely Microsoft will integrate the two somehow in the future. Adafruit Industries Page 40 of 43

41 The Moderation Process The author truly believes everything is in order: 1. The guide has been honed to perfection 2. The guide settings are like a fine wine 3. You have your video ready (if not an Adafruit superuser) 4. You have your CircuitPython or Arduino Code ready for GitHub (again, not superuser) Your guide is ready! Here is what you do: where is the switch that says ready and it sends the to learnmod@adafruit? The Initial Moderation The moderation team members (re. Mike B) will review the guide by doing the following: 1. Check that the content is ready as a guide. The guide should meet the standards Adafruit has as far as content and style. 2. Ensure Adafruit parts are in the Featured Products group and a parts list is in for Project guides. 3. Go over the style of the guide noting possible things such as page names, Fritzing, code, and resources. 4. Go over the checklist in this guide. Note issues to the author for consideration. 5. Add videos to the Adafruit Youtube account (Adafruit team members may do this themselves) 6. Add code to the Adafruit GitHub repository (Adafruit team members should do this themselves) Once things are agreed to between the initial moderation and the author, the moderator team (Mike) messages The Moderator Team Lead (Limor) to state the guide is ready for final consideration. Why do this? It saves Limor time in the moderation process so she can focus mainly on her role as lead engineer and as owner of the company. Final Moderation Limor has final approval authority. In Limor's absence, Phil may do this (no more court duty, please). There may be change requests in final moderation. Limor's experience catches things the author and the moderation team may have missed. She will usually contact the author directly although she may have the moderation team go over things with the author. After final moderation, Limor can mark the guide Live! See the next page for what that entails (no, it's not over yet!) Adafruit Industries Page 41 of 43

42 When Your Guide is Live How can I tell? There are a few methods you can tell if your guide is live: If you are an admin, looking a guide up on the admin panel will show, Draft, In Moderation, or Published. In the new Admin Panel, you can look at your guides: If you have access, you can look at the all guide list and see the status on the right side. Great Way to Tell if Published For Sure Suggestion from Limor: Don't just go to ( and see if it's there, use an incognito window in a browser (whatever your browser calls a private no cookie window) then go to ( and look. That way the browser will show what a "normal user" would see, not a person with special access to the Learning System. If you see the guide listed at ( in a private browser window, you know it's live for EVERYONE! Yay, published! Adafruit Industries Page 42 of 43