Git for collaborative documentation
Follow these tutorials to learn how to contribute to documentation hosted on github pages, and host your own docs!
Welcome!
These pages will guide you through the process of contributing to documentation hosted on GitHub, and show you how to create your own GitHub pages website (like this one!) to host your documentation or whatever else you’d like to share!
Reasons why people may chose to host their documentation on GitHub:
- It is relatively easy to make something which looks professional, and share it openly with the world.
- Version control allows you to efficiently track changes as your documentation grows, and keep a copy of all earlier work.
- There is a well established process to integrate contributions from friends, colleagues or strangers, and the ability to accept all contributions from named individuals or review changes before they are integrated.
- You can maintain an open “To Do” list in the form of GitHub issues, which you can use to advertise what you are working on, invite specific feedback, or allow others to suggest improvements.
- Your documentation can be integrated with Zenodo to generate a digital object identifier (DOI), turning your documentation into a citable research output for your CV.
These reasons make GitHub and excellent resource for openly sharing material which is intended for collaborative or community input.
By working though these tutorials, we hope you will feel the added benefit of increased confidence in using GitHub for other aspects of your work.
What are we doing?
These tutorials have been written for individuals with little or no experience of GitHub and the various prerequisite skills which are necessary to contribute to GitHub hosted documentation.
The problem
Using GitHub (or a related version control system) is an integral part of many reproducible and transparent workflows, particularly in academic science, technology, engineering, mathematics and medicine (STEMM) research.
Who knows how to contribute?
In disciplines where computer programming forms a core part of the training, the ability to use and contribute to GitHub material becomes second nature. In many other disciplines, GitHub and version control are emerging as “new” skills which are essential components of good open research practices. The lack of formal training in computer programming in these disciplines can, however, make the whole processes appear very complicated and intimidating.
Who should be able to contribute?
This fear factor or lack of exposure can mean that only certain groups of people are able to contribute to collaborative or community documentation. This is a problem because this means the material is generated by individuals with similar skills or experience, which may inadvertently make it inaccessible to anyone with a different skill set. Not only is this poor in terms of inclusivity, it also means the material is no robust to a wide range of readers. The knowledge becomes siloed within small groups, enabling only certain people to benefit.
I’m not going to lie - using GitHub for the first time is complicated, and contributing to community documentation can be intimidating, but with a little practice and some well structured support, this is something most academics can handle and everyone should have the opportunity to learn. We should all be able to participate in this effort for share knowledge.
The solution
These materials assume no existing knowledge of any of the skills required to contribute to or build your own GitHub. All they do assume is they you have valuable contributions to make (of course you do), but you don’t know the formal process to do it via the method which has become the norm in many areas of research.
You will learn how to use GitHub to edit text. That is it. We all know how to read and write and “track changes”, now you will learn how to do it following the GitHub system.
We are starting with text in the form of documentation as this is something everyone is familiar with. The process is the same no matter what you are creating, so this is just a safe starting ground for most people. Starting here will open doors for you to use GitHub in new and wonderful ways, boosting your CV and enabling you to join, influence and accelerate new communities of research.
Who are we
I am the Open Science Community Engagement Coordinator for the Wellcome Centre for Integrative Neuroscience (WIN) at the University of Oxford, UK. You can read more about the Open WIN Community and my work here.
More importantly, I am someone who has never had formal training in computer programming, but found myself drawn to it through my undergraduate, postgraduate, doctoral and postdoctoral work. I have been lucky enough to work with people who have shown me tools and practices which have been incredibly beneficial, empowering and enjoyable to use, and I want everyone to have that same opportunity.
“We” are also everyone who has contributed to making these tutorials available, including the developers of the resources listed in the acknowledgements, and everyone who has contribute to the material, especially those people listed in the contributing tutorial.
Thank you!
Thank you for taking the time to look at these pages. We hope you come away feeling inspired to start using these practices if you haven’t before. If you are already a Git Wizard, we hope you like what we have done and are ready to receive our contributions!