2.4. First impressions matter

Effectively communicating the basics of your project

Making it easy for readers

When we are looking for a project and find a website, or a repository README file, what do we expect? Usually we would like to easily understand the basics, to find out if it’s worth it diving deeper. In the same way, when people visit your project page for the first time, it’s ideal that they quickly understand:

  • what are you trying to achieve,
  • how are you working towards achieving it,
  • how can your project be used / contributed to,
  • how to contact you/your team.

The vision statement you defined earlier should guide these communication efforts. If you have clarified your project goals and scope, it will be easy to create an efficient front page that attracts people to your project.

The more people you reach with your message the better. You will probably have an audience in mind, as you will see in following sections. But the experience of other open hardware projects, such as White Rabbit at CERN, shows that projects can be picked up by the most unexpected users!

Website, README, platforms…

READMEs are a good practice in software development that makes it easier for readers to find basic information on a project. The README file (whose name by convention is written in all-caps, and represents a request to one and all— “read me!”) lives on the web, as part of a collection of working documents on your project, called a “repository”. The aim of the README is to welcome, orient, and encourage newcomers to participate.

However, in hardware projects communication is slightly more complicated. As you will see in the Version Control section, you will probably have a repository for your project source files, including software, design, electronics. But if you just add a README to a repository and expect people to see your work, you will be quickly disappointed. Not all hardware audiences are familiar with software practices; and different from software development, there are multiple documentation platforms for hardware.

An easy workaround is to create a project website, something anyone can find using a search engine, and that you can easily add as a link in social networks, or other communications. One possibility is to create a webpage for free using the services provided by version control platforms (like GitHub or GitLab). These services provide static web pages that are perfect for functioning as a presentation of your project. There are multiple tutorials online showing how to do this, you can find examples in the Resources section below.

Probably the most important thing once you have your front page published, is to keep it updated. Nothing is less motivating than finding a project website that looks so outdated that it makes you think the project is dead. This is another advantage of making web pages with GitHub/GitLab: you can easily update the website just by modifying the README or source file.

Great open hardware front pages

  • Audiomoth, an example of an open hardware tool researchers are using around the world
  • OpenFlexure, an open 3D-printed microscope for education & research
  • Otto DIY, an open hardware robot for STEM education

Assignment: Create a basic project webpage

Use the information you gathered in the Open Hardware Canvas exercise as a starting point. Be sure to:

  • Say hello! Welcome people to the project. It’s great to introduce yourself here, so people know they’re dealing with a person or group of real people. Let potential contributors know you’re excited that they’re here to learn more
  • Write a project description: what you’re doing, with who, for who, and why. Sound familiar? This is a version of your project vision. Expand your sentence as a full paragraph, adding any new details about aims and the problems you plan to solve that surfaced in the Open Hardware Canvas. Try to phrase this so it’s understandable and appealing to a wide variety of people, not just those in your field.
  • Explain what makes your project special, useful, exciting!
  • Show how to get started using or contributing to the project. If you’re just getting started, this could be as simple as asking people to attend a planning call or kick-off event, or sign up for an email newsletter about the project. If you’re not sure quite how to get users involved just yet, don’t worry! In the next modules you’ll devise some ways for newcomers to get involved, and create contributor guidelines. Once you’ve done the next module, you can come back here and add a link to contributor guidelines to this section.
  • State what resources are most needed. If you have a need for a special kind of help, expertise, or a resource like event space, be sure to mention that here.

Resources

next: Building Open Projects  

Help us improve content and suggest changes to this page.