What is Github Document Management?
Github document management refers to the management of documentation for software projects that are created and hosted on Github. You can use Github for private or open-source document management.
What is Github?
Github is a website that you can use to host the code for your software projects. To understand how it works, let’s look at an example.
Let’s say you want to build software or an app. Your team is distributed all over the country, or even all over the world.
The Legacy Way
One way you could work, let’s call it the Legacy Way, is by having team members work on the software source code independently and share the updated versions with other team members via email or some other file-sharing system.
Version Control
One thing that is extremely critical in software development is version control. Software is developed in stages or phases. The first working prototype with some working features may be called version 1. The software development team may work on it to produce an improved version called version 2, and so on.
Software teams need to know exactly what source code, functionality, and issues (aka bugs) are associated with each version of the software. This is because sometimes development creates new and unexpected problems, and you need to go back to an older version to help fix the problems.
Version control or any type of control for that matter is super difficult with the Legacy Way. With so many files flying around, it is easy to lose track of what works and what doesn’t, or which file has the latest code and which one has the older code. You would have to search through a vast number of files and would still find it hard to locate the information that you need.
The Cloudy Way
Another way of developing the software, let’s call it the Cloudy Way, would be to use Github.
With Github, you build an online repository where the source code for the software and related documentation is stored. A team member working on the project can make changes online and submit them to the repository. The team member can also download the latest version of the code, work on it, and then submit changes to the online repository through a “pull request”. The latest updated version of the software, hosted on Github, will be available to all team members involved with the project.
Rather than only allowing one developer to work at the expense of blocking the progress of others, Github allows all team members to work at the same time. Version control tracks every individual change by each team member and helps prevent concurrent work from conflicting.
Version control doesn’t only track the changes in the code, but also the author, date, and written notes for the purpose of each change. This helps to develop a comprehensive history of all changes made over the software development lifecycle.
What is Git?
Git is free and open-source software that allows you to track changes in any set of files. It keeps track of every modification to the files in a special kind of database. Git is usually used for coordinating work among programmers working collaboratively to develop source code for software.
Github uses the version control and source code management functionality provided by Git and offers several additional features.
Why Github?
Github offers many features that make it a very popular platform for software developers from all over the world. It is the most prominent source code host: over 60 million repositories were created over the course of one year through September 2021, and over 56 million developers were using the platform.
Code Hosting
You can easily host the code for your software along with the documentation. GitHub keeps your public and private code available, secure, and backed up.
Project Management
Every repository on GitHub comes with the tools needed to manage your project. You can either open your repository to the community for public projects or secure it for private projects.
Your developers and project managers can come together to coordinate, track, and update their work so that projects are transparent and stay on schedule.
Third-Party Integration
Github allows you to integrate with tools and services that connect with GitHub to complement and extend your workflow
Reporting and Analytics
With traffic analytics, you can view detailed analytics data for repositories that you’re an owner of or contribute to.
Vulnerability Scanning
You can use code automated scanning to find security vulnerabilities and errors in the code for your projects.
User Friendly
Depending on your preferences, you can use either a command-line interface or a graphical user interface.
Github Document Management System
Github is a tool that helps you develop software and share it with your team or with the world. However, it will be difficult for users to make the best use of your software without good and comprehensive documentation. There is no denying that documentation is the ultimate advertisement for technical stakeholders. Not only that, many organizations make their purchasing decisions based on the quality of a product’s documentation.
That is why Github provides tools for creating and sharing project documentation. You can also create websites for your documentation with a Github service called Github Pages.
Docs Like Code
The approach taken by Github for documentation is the same as for software source code: Github wants you to treat your documentation like your source code, a body of work that is constantly being iterated and becoming a bit better than the last time you updated it.
This approach is called Docs like Code, which is basically a mindset that allows to you create and maintain your documentation just as rigorously as you do your programming code. It also refers to the philosophy of using the same tools that are used for writing code for writing documentation.
The Docs as Code approach brings multiple benefits for writers such as better integration with development teams and the ability to block merging of new software features if they don’t include documentation.
Document Management with Github
The following is the sequence of steps that you would need to follow to create documentation on Github.
Create a Repository
The repository is where are your data will be stored. You can create separate folders in the repository for the different documents that you want to create.
Create Documents
The documentation files are all in a format called Markdown, which is a simple and easy text format that allows you to generate basic HTML without knowing HTML itself. It uses simple tags to format text on a website.
Short documents consist of a single markdown file. All content is contained in the “index.md” file and the table of contents on the side of the page is created using the header tags in markdown.
Multi-page documents include folders for individual languages and a single markdown file for every chapter of the document. They also contain a file called “SUMMARY.md” that creates the table of contents for the document and a file called “README.md” that serves as a first/landing page for your document.
Pull Request
Once you have edited an existing document or created a new one, you need to initiate a pull request. This indicates that you have completed your changes and lets the other team members know that they can review your changes.
Github Pages
GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files from your repository on GitHub, optionally runs the files through a build process and publishes a website. You can host your site on GitHub’s domain or your own custom domain.
Jekyll
GitHub Pages supports Jekyll, a software library that was written by one of Github’s co-founders. Jekyll converts text files into a static website or blog. Jekyll also includes support for many helpful tools like variables, templates, and automatic code highlighting.
Conclusion
With Github, you can develop software and its documentation. The beauty of the Github approach is that it allows multiple team members to work on projects at the same time and manage both software code and its documentation.
You can iteratively improve the software and its documentation at the same time. Github document management will not only manage version control for your source code, but it will also manage the version control for the documentation so that you can always access previous versions if the need arises.
With tools such as Github Pages, you can easily publish the documentation to the web where it will be accessible for all users.
Other than working on private projects, you can also contribute documentation for open-source software projects on Github.
FAQ
Here is a frequently asked question about Github document management.
Is Github a document management system?
Github is a platform that offers many features for collaborative software development. The power of software cannot be fully realized without good and comprehensive documents. This is why Github includes features that allow you to create and share documentation for the software projects that you are working on.
If you are new to document control with Github and are looking to learn more, we recommend taking our Technical Writing Certification Course, where you will learn the fundamentals of Github documentation.
