So you just built a super-mega robot project that you want to share with the world. Super! But now you’re faced with an entirely new and different problem: documenting the process for the world to see. It’s enough to drive you back down into the lab.
- What software should I use to create my project site?
- How deep down the rabbit hole should I go when it comes to documenting the project?
- What toppings do I want on my something-to-eat-while-hacking pizza?
We’re not going to get into the age old “pineapple or no pineapple” debate, but it’s important to note that the topic of how to share a project with the world has as many choices as toppings, and just as many opinions. The answer will always be simple: Do what works best for you!
The purpose of this article is to give some options to somebody considering sharing their projects online. There isn’t enough room to talk about every single option available to a hacker, so be sure to fill in your favorite options in the comments below. Let’s dive in!
Considerations Before You Start
Before even beginning to look into all of the options for hosting your projects, there are some basic questions that we need to answer. Consider the following:
- Who is your audience, and how will they expect to consume what you present?
- How deeply do you want to document your project, and what kind of media will you present?
- How will people find your project?
Let’s talk about each of these topics for a moment.
Who is your audience?
This is probably the question that will affect your choices more than any others. Who are you writing for? Are you sharing new ideas for people who are experts in your chosen subject? Are you trying to expose your area of expertise to a new crowd who know little about it? Try to answer these questions before you start. If you’re not sure, that’s okay. You’ll figure it out as you go.
If you’re writing for people who are expected to know as much about your subject as you do, you’ll likely be limiting your audience quite a bit. Instead, try writing for a specific person who knows a bit less. Pick a relative, friend, or another person that you know who you’d like to interest in your project, and write it for them.
For example, if you’re writing an article about a new bed leveling method for 3D printers, take a moment and describe why bed leveling is a problem and perhaps introduce common solutions and their drawbacks. This will help your audience to understand what makes your project unique, and will add a lot to their enjoyment.
How deeply to document your project?
This question is closely related to your audience. If you intend to do deep dives into a subject and explain its underpinnings from scratch, you may choose a platform more suited for long form content vs one geared toward a quick share.
Deeper documentation may mean integrating video, pictures, and text, so you’ll want to pick platforms that will let you integrate all of these media into one presentation.
How will people find your project?
This is where some research will be required on your part. Software developers will find drastically different answers to this question than somebody who wants to publish a deep dive on debugging shift registers in obsolete 10-bit computers.
A great way to determine this is to go to your favorite search engine and do a search for the that you would do to find your own content, and see where others are publishing their projects. You can also take a look at their approach to sharing their works and decide which elements you may wish to emulate, change, or leave out altogether.
Choosing A Platform
Now that you’ve had the opportunity to consider the approach you’d like to take, it’s time to make a decision about how you’d like to share your project with the world. This brings up many of its own questions, but rather than run you through another laundry list of questions, we’re going to look at self-hosted options as well as various services and discuss the pros and cons of each.
In a previous article, we talked about ways that you could host your own project website at home, and that extends easily to hosting things on a very cheap VPS, a free cloud computing instance, or a solar wind and rain powered piduino8266. You get the idea. With the self-hosted option, you’re responsible for the server administration.
We’re going to get this one out of the way right away for two reasons: If you have never blogged before and want to run your own software, it’s hard to go wrong with WordPress.org. Originally designed as a blogging-only platform, it has morphed over the years into being a full on website builder. There are countless themes that let you change the look and feel of the website with just a download, and there are as many plugins that extend the functionality of WordPress.
If you’re wondering just how useful it is, it’s noteworthy that Hackaday, and this very post, are all done in WordPress, and some of the largest sites on the Internet are using WordPress too. WordPress has the great advantage of not requiring any coding skills. Because it’s a big project that’s widely used, it gets lots of security attention, on both the white hat and black hat sides of the fence, so you’re going to need to keep your install up to date. This isn’t hard, but there’s some necessary management overhead.
Ghost is a website builder and blogging platform that is based on NodeJS rather than PHP. It’s hailed as being very fast and easy to work with and for a while it was what all the cool kids were using.
Ghost is great if you like to code in NodeJS and don’t want to build something from scratch.
HTML5 and Friends
Building an HTML5 site from scratch or a template is an excellent way to go if you’re in it for the development just as much as for the project sharing.
Maybe running your own server and website is beyond what you’d like to do, but you still want to have somewhere to share your works and projects. You’re in luck- there are countless services just waiting to host your content, and we’re going to talk about all the ones you can use that are free (as in beer).
WordPress.com is a hosted version of the WordPress.org software. Your site is hosted directly on the WordPress.com servers, and that comes with some limitations. But if you like WordPress, or want to try it out without spinning up a server for it, it’s an excellent option.
It may seem like an odd choice, but by creating a new Repository in Github, you are given an area to upload files, write HTML, and link to outside sources. Each repository can have a Readme page that shows up when the Repository is loaded, and that page can embed the pictures and other media that you upload to the Repository. Github is especially a good choice if your projects are software only, but works fine for others, too. And, Github has a free tier of service. And, of course, it’s versioned.
Blogger.com has been around for ages, and is the place where many bloggers have started. Some have grown away from it, while others have utilized it for many years as a reliable place to host your content. Because it’s a blog-only platform, it doesn’t lend itself to building a website about your project, but rather to sharing multiple projects over time.
Imgur.com / YouTube
Imgur.com is a photo sharing community that is often used to document projects that are mostly photographs only. Sharing other file formats isn’t allowed, but it could be used in conjunction with Github for sharing files. If your project is video based, the same things are true for YouTube. The weakness with YouTube is that it’s not easily searchable, but it is an excellent way to demonstrate projects that are documented more thoroughly in a blog or other website, where the written word reigns king.
It may seem rather self-serving to suggest Hackaday.io, since it’s our own platform, but the truth is that if this post were being written elsewhere, it would still be on the list. It’s designed to be an excellent way to share files, pictures, and embed YouTube videos. It has the added strength of being searchable on a platform full of similarly minded hackers. Getting a simple page up and running is extraordinarily easy, and there’s even a “submit tip to Hackaday” button. What more do you want?
Regardless of which medium you choose- written, photographs, video, or some combination thereof- just get out there and get started! A great way of getting your feet wet is to go through your backlog of completed projects and documented using your chosen means, and see how it feels.
Your first works will probably a bit rough, but once you develop a style and a method, it will get a lot easier. Don’t worry about perfection, and especially do not worry about the Internet Popularity Contest. You’ll never be able to please everyone, so focus on your chosen audience and let the cards fall where they may. Every content creator has to do this to some extent.
No doubt, there are countless other options that we’ve omitted because let’s face it, platform options are like pizza topping combinations: there are too many to list! So this is your opportunity to shine- let us know about your favorite platform in the comments below.