How to Create a High-Quality Project Tutorial

Crafting the perfect set of build instructions and documentation is imperative to the online success of your project. If you document your project with clear photos, concise and easy-to-follow wording, and you record each step of the process, chances are your content will get spread far and wide across the internet. I have compiled a list of suggestions that will help you do just that.

Step One: Project Planning

Meticulous recording of the planning process can be as helpful to you as it is to others. Say, for example, you're designing a circuit. Rather than creating a back-of-the-napkin-style circuit diagram consider using one of a whole number of circuit design programs. When you craft your circuit in a software suite such as Fritzing or circuits.io you are both helping yourself by documenting different variations of your design as well as helping others by providing much clearer schematics. In addition, you're giving others a virtual copy of your design to modify to fit their needs.

This same principle applies to other areas of your project such as project housings. Try designing everything you create in 2D or 3D CAD software before you start constructing it. This process can help you iron-out potential problem areas as well as provide readers with a clear representation of what the project will look like.

Step Two: Part Sourcing

Sharing the full list of parts you used is important to help others replicate your project. The Hackster project editor has a special section to enter parts (under "Things"), and they have a database of verified parts to choose from.

It is certainly tempting to source parts for your project from across the internet. However, this presents a potential problem for people trying to replicate your build. They need to go through the process of entering their shipping/payment details into every website from which they need to order parts, and they may need to pay much more in shipping costs. Consider sourcing all of your parts from the same place, or at least finding links to each part on one source's website.

All parts entered in into the Hackster database are pre-linked to a reputable and secure store - choose these whenever you can even if they come from a different source than your chosen one.

Step Three: Documenting the Build

The key to this step is good photos. For most of my projects I actually like to order 2x the number of parts that a specific build would require. I do this because I first like to build my circuit without having to worry about documenting the process. I then go back and build it again, making sure to take photos of everything I do. Obviously this wouldn't apply to every project, such as those that require expensive materials, take a long time, or are constructed on a breadboard. However, if you're constructing simple soldered circuits you might want to consider this.

Please check out this separate tutorial I created for in-depth tips and tricks on how to take good photographs: https://www.hackster.io/AlexWulff/how-to-take-well-composed-photos-of-your-hardware-project-ffd2c5

The trick to taking high-quality photos is sufficient lighting. Even with a low-quality cell phone camera you can take great photos as long as the lighting is right. I choose my workspace around the available lighting because it aids both my cameras and my eyes in seeing what I'm doing. Bright, overhead lighting is desirable.

Macro lenses are another great investment for project photography. They allow you to focus on extremely small objects at a very short distance away. The images above of my soldering iron tip and an ATtiny were taken with a macro lens. Macro lenses allow you to document the intricacies of your project such as dense wiring or small surface details. You can buy macro lenses of varying quality for cameras ranging from your iPhone to expensive DSLRs.

If all you have is a smartphone or a point and shoot with normal lenses then try and take all of your photos directly overhead. Having all your photos shot from the same angle actually helps the reader of your tutorial to get a sense of continuity from one shot to the next

As a last photography tip I recommend taking way more photos than you think you need. If you're not shooting with film, photos are free. There have been many instances in which I have been writing up a project and wished that I took a photo of a specific step.

Step Four: Taking and Choosing a Cover Photo

Other than your project title, the cover photo is what motivates people to click on your project. It's in your best interest to make it look nice!

First-off, photos of breadboarded circuits almost never turn out looking very good. It's generally impossible to tell what's going on, and they just don't want to make someone read your tutorial. If your project is breadboard-based, consider highlighting a central component to your project and using that instead. You can also find a free stock image from sites like pixabay.com to use.

Try going to https://www.hackster.io/projects and seeing what cover images catch your attention. If it interests you, it'll likely interest other people, so try replicating that! If you took video of your project you can use giphy.com to create a GIF for your cover image. GIFs will appear in reduced quality as compared to a still photo, but their movement is eye-catching.

Something simple, elegant, and eye-catching is often the best choice.

Cover images on Hackster are in a 4:3 format. In order for your image to appear correctly, it's vital to ensure that you crop the right way. Hackster has a feature that allows you to crop your cover images when you upload them. Try your best to keep the subject of your image centered. If you're using a GIF, limit camera motion to facilitate this process. If you want more fine control you can use a program such as preview on Mac to crop your images ahead of time.

Step Five: Writing Human-Readable Software

Your software won't be useful to anyone if it's a black box. Having inputs trigger outputs without any sense of what is happening in between leads to hard-to-maintain and hard-to-read code.

Take a look at the following Arduino C++ program:

//Code produced by Alex Wulff: http://www.AlexWulff.com 
#define BUZZ         0 
#define LED          1 
#define BEEP_DELAY   30
#define LIGHT_DELAY  200
#define INITIAL   5000 //Value is in milliseconds.
//10,000 ms yields a total sequence time of 46.5 Seconds 
//20,000 ms yields a total sequence time of 91.5 Seconds 
//30,000 ms yields a total sequence time of 136.5 Seconds 
//You get the pattern. Each 10 seconds yields another 45 
//seconds of total time on the sequence. 
void setup() { 
 //Initialize the output pins
 pinMode(BUZZ, OUTPUT); 
 pinMode(LED, OUTPUT); 
 //Flash the light to make sure the device is working 
 for (int i = 0; i < 5; i++) { 
   digitalWrite(LED, HIGH); 
   delay(LIGHT_DELAY); 
   digitalWrite(LED, LOW); 
   delay(LIGHT_DELAY); 
 } 
} 
void loop() {
//Iterate 50 times, decreasing the loop delay by a factor of 1/i each time
 for (int i = 1; i < 50; i++) { 
   digitalWrite(BUZZ, HIGH); 
   digitalWrite(LED, HIGH); 
   delay(BEEP_DELAY); 
   digitalWrite(BUZZ, LOW); 
   digitalWrite(LED, LOW); 
   delay(INITIAL/i); 
 } 
}  

It exhibits a variety of different characteristics of "good" code. I'll outline these below:

• Don't be afraid to comment. Comments let whoever is reading your code know what something does and, if needed, why you did it that way. It also makes it much easier when you come back to your code at a later date to understand the general program flow.

• Stay away from hard-coded values. Rather than use the raw pin numbers in your sketch, consider using #define to assign them a name instead. This makes it much easier to understand what's going on, as well as change pins on the fly. This same principle applies to actively-reused values like specific delay times.

• Use consistent whitespace. Inconsistent tab spacing leads to indecipherable code; pick a whitespace format and stick with it. The Arduino IDE defaults to two spaces, but many text editors use one tab.

• Arduino has a style guide here: https://www.arduino.cc/en/Reference/StyleGuide. While I don't agree with every tip in here, the most important thing is consistency. If you use one way to write if statements stick with that way.

Lastly, Hackster has a separate section for code. You can add code samples to the story, but you should include all the code files into the code section, under "Attachments".

Step Six: Structure of the Write-Up

The primary thing you want to avoid in a build documentation, structurally speaking, is a wall of text. Human eyes like structure. We naturally jump around from headings to subheadings to paragraphs; one long block of text hinders this natural progression without providing any reference points. I recommend formatting your posts in a step-style manner with headings for each step (use the H icon in the story editor to turn text into a heading). Take a look at this very tutorial for example - it clearly breaks up the process of writing a project build into specific, chronological sub-sections.

Inside of each sub-section I also like to use lots of small paragraphs. This signals to your reader that you're moving on to another related but slightly different topic, like I just did with this new paragraph. I also like to punctuate the start of each step with a photo to keep the reader more engaged. Humans like lots of photos.

Step Seven: Write.

This is by far the most important part of your whole write-up. Writing a good tutorial is a skill that can take a lifetime to master, but hopefully these tips will help you improve your tutorial skills.

• Avoid simple spelling errors. Nothing screams unprofessional like a typo. Double and triple-check your work to ensure that none slipped through.

• Avoid grammatical mistakes. These can be much harder to detect in many instances. I often see many comma splices, these are bad (that last sentence was a comma splice - the comma separated two independent clauses). Messing up your apostrophes can also look unprofessional. Services such as Grammarly can help detect these errors for you.

• Vary your sentence structure. Try mixing up longer-winded sentences with short sentences. Oftentimes simple sentences are more impactful than their wordy counterparts. Examples in this post include "Humans like lots of photos," "The key to this step is good photos," and many more. Another good technique is to separate two independent clauses with a hyphen (-) or a semi-colon (;) to add emphasis.

• Keep most of your sentences short. It can be very difficult to read sentences that span a whole paragraph. If you feel like a sentence is too long, try taking out some modifier words or breaking it up into multiple sentences.

• Mix technical and non-technical language. There's a very fine balance between overwhelming the reader with part numbers and formulas and making your tutorial read like a poorly written novel. If you use technical terms be sure to explain their meaning (unless obvious), but also keep language clear and concise. If your audience is more technically-oriented, adapt your language accordingly.

• Acronyms: they're a great way to be more concise, but spell out each acronym once before you use it. Unless it's something really simple.

Step Eight: Choose a Good Project Name and Elevator Pitch

The name is what people first see about your project and is the first indication of what it is. The elevator pitch allows you to provide a little more info to the reader in deciding whether they should click to view your project. Give them some love!

Avoid generic titles and clearly state what your project is. At the same time, the name and pitch are not the place to list all the components you used. Mentioning components is only useful when the project is about how to use them in a specific context, like "How to install Windows 10 on a Raspberry Pi".

Step Nine: Publishing your Project

Once you're done writing it all up, it's time to share your project with the world! Head on over to the Publication Settings and fill in the details before turning Privacy settings to "Discoverable".

In this step, particular attention should be put on tags. Tags help categorize your project, so that other people can discover it by browsing topics they're interested in. In that respect it's important to choose tags that are neither too specific nor too broad. Since Hackster also has special pages for platforms such as Arduino and Raspberry Pi, as well as for each component such as Arduino UNO and Raspberry Pi Zero, those are considered redundant and don't fit well as tags. Good tags depict a topic such as "smart home" or "drones", or a technology like "bluetooth low energy".

To help with choosing the right tags Hackster has a pre-set list of tags you can choose from. If you have over 1,000 reputation points you can also contribute your own tags.

That's all!

If you have any questions or suggestions don't hesitate to leave a comment below.