This repo serves as a template/demonstration for using GitHub Pages to build your custom site. You can learn more about GitHub Pages through the GitHub Pages user guides.
See this page rendered as a GitHub page.
*ToDo: implement Jekyll theme and format all files for Page layout. https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll
This repository serves as an example template to help you create great documentation for your Open Hardware projects by using GitHub Pages. It contains examples of the recommended files and filestructure that is commonly shared in open source hardware projects. Sharing all of these resources is optional, so please fill out everything you can, and delete the files you aren’t using.
You can use this template and replace all of the files/text with your own documents.
Here are a few examples of great GitHub Pages.
The proposed structure of folders within this template is based on the ‘Best Practices for Open-Source Hardware’ document published by the Open Source Hardware Association.
You can also learn more about open source documentation through the GitHub Open Source Guides , but it is more catered for open source software than it is hardware.
You are free to modify this document as it best suits your needs, by overwriting the text on each paragraph and adding/deleting any information or extra files that you consider useful.
You can start by deleting this section, including this line of text.
Write here a short description (two or three paragraphs long) on which you define: What is your project? What is it good for? How do you make it work?
Try not to use technical jargon or complicated words. Remember that people who will read your description might not have the same level of expertise, or they might not be on the same field of knowledge as you.
Explain how you expect your project to work. It is not necessary, however, that you write every little detail of its functioning. If you need to present a more detailed explanation of your project, we recommend you post a link to a website or another .txt file inside of the ‘docs’ folder.
To make your documentation more useful, indicate the level of development of your project. Some indicators could be: “stable”, “beta”, “incomplete” or “barely working”.
You can also add to this section the corresponding credits in case your project is a derivative work from another project. You can also add the names or pseudonyms of the people who contributed to your project, the type of copyright/patent license and last date of modification.
Add to this section the last relevant changes or corrections that you have made to your project. It is important that you notify about changes that modify the behavior of your project or the outputs that you expect it to generate.
Here’s an example of changes to the latest version ‘0.1alpha’:
Corrections:
You don’t need to write down the whole history of changes. Instead, you can make a new file in this folder named ‘changelog.txt’ with a list of all the changes made (preferably on inverse chronological order):
You can check the complete log change history in the file ‘changelog.txt’.
If the bill of materials for this project is very short you can put it right here. Otherwise, you can create a file named ‘bom.csv’ or any spreadsheet file where you can detail the bill of materials and costs. Try to use open formats as much as possible (share an .ods formatted file instead of an Excel .xls file, for example).
Use this section to detail what is required in order to make your project work. You need to put the requirements or previous needs for software in order to make it work, or the tools that are needed to build it.
We give you an example.
Software requirements:
Required tools:
If the construction procedure is simple, you can write it down in this section. However, if you think it will need more details, you can create a file named ‘build.txt’ where you can elaborate on the construction procedure details.
Likewise, if the procedure for utilizing the associated software to the project is simple you can write down the details in this section. If said instructions are too long, you can create a file named ‘usage.txt’ and reference it from this section.
The folder structure is very important for your project, because it will allow you to organize your projects and will also allow others to easily share changes or improvements. This structure isn’t set in stone, however, so you can modify it so it suits your needs.
Remember that inside every folder we strongly recommend you to include a file named ‘readme.txt’ where you can describe its contents.
Within the folder structure we recommend to include at least the following folders:
We recommend you to add a text similar to this in your projects:
The following project is shared “as is”, with the sole objective of being useful. The creator(s) of the described piece of hardware and its associated software cannot guarantee its correct functioning under any circumstance. The author(s) of this project will not be held responsible for any material, personal or economic loses to you or any third parties that may arise from using this design. This project will not be used under any circumstances on systems whose responsibility is critical, or from which people’s lives depend on, directly or indirectly.
Add here the license that your project’s source code has been subjected to. You can read more about how to choose a license by reading the license.txt file, which you should replace entirely with the license you choose for your product. We would also love it if you add the attribution note for the template at the end of this file.
This README.md template has been developed by the openhardware.sv community in order to make project documentation easier. This template has been protected under a CC BY license. You can modify it and redistribute it as long as you keep this author attribution note.