What’s the Best Way to Document the Creation and Abilities of a Robot?
Reddit Robotics’ group has a lot of smart people. I know they’re smart because they ask really great questions, like when MrPotatoJunior asked this one: What is the best way to document the creation and functionality of a robot?
This is a great question – staying organized is so hard with so many projects.
Does your method work?
Let’s see some qualifications first, hey? I sell robots online. My method has been tested in a working environment and refined for the last 18 months. Here are some projects I documented on Instructables before “going pro”.
The format is the same each time: overview, BOM, step-by-step assembly instructions, copy of source code, final notes. Today I would add design files for parts that need to be manufactured at the end and the BOM can reference them along with a manufacturing estimate. I would also add testing wherever appropriate – not just before or after code. It may require several test programs to validate each piece works before trying to turn on the whole machine.
Drawings
Drawings are critical. You will develop great drafting skills in order to communicate your ideas clearly. Nothing I’ve found is faster for explaining how things fit together. Nothing I’ve found is faster for checking design ideas before investing time in a 3D modelling program.
For drawings I use an 11″x14″ sketchbook. Most drawings take up the center 1/9th of the page, leaving me room for notes and corrections around the edges. Date, project name, part name, and version on every page. One idea per page. I go through a lot of sketchbooks. I sometimes put a piece of tape sticking out the top of the sketchbook as a page marker so I can find important stuff fast.
When I make a 3D model I store it in projects/part_name/version-date for the filename. Same goes for drawings of circuits. I have a separate folder projects/project_name/version which then references the parts in other folders. This works great because sometimes I only make one model of a part (like a NEMA17 stepper) and reuse it in many other projects.
BOMs
I keep a Bill Of Materials (BOM) in an excel sheet in projects/project_name/version. Every part, where I got it, what it cost, and how many I had to get at once – some things only come in a 10 pack. Some get cheaper when bought in bulk.
Version control is your friend. Nothing sucks like breaking the design of a well-functioning robot when all I wanted to do was experiment with a new idea.
Physical storage
For physically storing my projects, I use clear plastic shoe boxes from Home Depot. $0.96ea. labelled on the front, stacked three high. Only one project needs a double-wide box. Only one needs a 2×2 sized box. The rest are actively being used (like 3d printers) and don’t go in boxes.
Code
When documenting code, I write the intention before the code. So I explain what I’m going to do in comment lines and then I write the code between the comment lines. There’s no such thing as “obvious” or “self-documenting” code – what’s easy for you might be hard for me. Heck, sometimes what’s easy for me is hard two months later when I don’t remember writing it!
For more information, read all the responses on Reddit here.
