So you’ve just built a super-mega robot project that you want to share with the world. Great! But now you’re faced with an entirely new and different problem: documenting the process for the world to see. It’s enough to bring you back down to the lab.
- What software should I use to create my project site?
- How far do I have to go down the rabbit hole to document the project?
- What toppings do I want on my pizza something to eat while hacking?
We’re not going to get into the 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 it has toppings, and 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 someone considering sharing their projects online. There isn’t enough room to talk about all the options available to a hacker, so be sure to fill in your favorite options in the comments below. Let’s dive!
Before we even start looking at all the hosting options for your projects, we need to answer a few basic questions. Consider the following:
- Who is your audience and how will they expect to consume what you present?
- How much do you want to document your project and what type 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 other. Who are you writing for? Do you share new ideas for people who are experts in your chosen field? Are you trying to expose your area of expertise to a new audience that knows little about it? Try to answer these questions before you start. If you’re not sure, that’s okay. You will understand it as you go.
If you’re writing for people who are supposed to know as much about your topic as you do, you’ll probably be limiting your audience a bit. Instead, try writing for a specific person who knows a little less. Choose a relative, friend or other person you know who you would like to interest in your project, and write it for them.
For example, if you’re writing an article about a new method of bed leveling for 3D printers, take a moment and describe why bed leveling is a problem and maybe present some common solutions and their drawbacks. This will help your audience understand what makes your project unique and add a lot to their enjoyment.
How far should your project be documented?
This question is closely related to your audience. If you intend to dig deeper into a topic and explain its basics from scratch, you might choose a platform more suited to long-form content rather than one geared towards quick sharing.
Deeper documentation can mean integrating videos, images, and text, so you’ll want to choose platforms that allow you to integrate all of these media into a single presentation.
How will people find your project?
This is where some research will be required on your part. Software developers will find radically different answers to this question than someone who wants to post a deep dive into debugging shift registers in outdated 10-bit computers.
A great way to determine this is to go to your favorite search engine and do a search on what you would do to find your own content, and see where others are posting their projects. You can also take a look at their approach to sharing their works and decide which elements you want to emulate, modify or omit altogether.
Now that you’ve had a chance to think about which approach you’d like to take, it’s time to make a decision on how you’d like to share your project with the world. This brings up a lot of its own questions, but rather than giving you another 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 post, we talked about ways you could host your own project website at home, and that easily extends to hosting stuff on a very cheap VPS, free cloud instance, or a piduino8266 powered by solar wind and rain. You had the idea. With the self-hosted option, you are responsible for server administration.
We’re going to eliminate this one right now for two reasons: if you’ve never blogged before and want to run your own software, it’s hard to go wrong with WordPress.org. Originally designed as a blog-only platform, it has evolved over the years into a full-featured website builder. There are countless themes that allow you to change the look of the website with a simple download, and there are just as many plugins that extend the functionality of WordPress.
If you’re wondering how useful that is, it’s worth noting that Hackaday, and this article itself, are all made in WordPress, and some of the biggest websites use WordPress as well. WordPress has the great advantage of not requiring any coding skills. Because it’s a big project that is widely used, it receives a lot of safety attention from both the white hat side and the black hat side of the fence, so you will need to keep your installation up to date. It’s not difficult, but there are management overheads involved.
Phantom is a website builder and blogging platform based on NodeJS rather than PHP. It’s hailed as very quick and easy to use and for a while it was what all the cool kids used.
Ghost is great if you like coding in NodeJS and don’t want to build something from scratch.
HTML5 and its friends
Building an HTML5 site from scratch or a template is a great way to go if you’re in it for development as much as project sharing.
Maybe running your own server and website is beyond what you’d love to do, but you still want to have a place 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 cover all of 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 WordPress.com’s servers, and that comes with some limitations. But if you like WordPress or want to try it out without creating a server, this is a great option.
This may seem like a strange choice, but creating a new repository in GithubGenericName, you have an area to upload files, write HTML code and create links to external sources. Each repository can have a Readme page that displays when the repository is loaded, and this page can embed images and other media that you upload to the repository. Github is especially a good choice if your projects are just software, but works well for others as well. And, Github has a free tier of service. And, of course, it is versioned.
Blogger.com has been around for ages and is where many bloggers started. Some have moved away from it, while others have used it for many years as a reliable place to host your content. As it is a blog-only platform, it does not lend itself to creating a website about your project, but rather sharing multiple projects over time.
Imgur.com is a photo sharing community that is often used to document projects that are mostly just photographs. Sharing other file formats is not allowed, but it can be used in conjunction with Github to share files. If your project is video-based, the same things are true for Youtube. YouTube’s weakness is that it’s not easily searchable, but it’s a great way to demonstrate projects that are documented more thoroughly in a blog or other website, where the written word reigns supreme.
It may seem rather self-serving to suggest Hackaday.io, since it’s our own platform, but the truth is that if this post was written elsewhere, it would still be on the list. It’s designed to be a great way to share files, images, and embed YouTube videos. It has the added strength of being searchable on a platform full of like-minded hackers. Getting a simple page up and running is extraordinarily easy, and there’s even a “submit a tip to Hackaday” button. What else do you want?
Whatever medium you choose – written, photographs, video or a combination of these – get in and go! A great way to get your feet wet is to go through your notebook of completed projects documented using your chosen mediums, and see how you feel.
Your first few jobs will probably be a bit rough, but once you’ve developed a style and a method, it will become much easier. Don’t worry about perfection, and above all don’t worry about the internet popularity contest. You can never please everyone, so focus on your chosen audience and drop the cards where they may. Every content creator has to do this to some extent.
Undoubtedly, there are countless other options that we’ve left out, because let’s face it, platform options are like combinations of pizza toppings: there are too many to list! So this is your chance to shine – let us know your favorite platform in the comments below.