GitHub Quickstart Guide

Overview

I used Docusaurus to generate a static site to host a user-friendly quickstart guide to contributing to open-source projects on GitHub. Inspired by my work with Paraqlet Solutions, in which I used GitHub to manage version control for a brand style guide, I sought to create a step-by-step guide to using GitHub Desktop to review and commit changes to a GitHub repository.

I used GitHub Actions to automate deployment via a CI/CD pipeline, generated a Docusaurus site, and wrote the guide in Markdown.

You can view the final product on GitHub Pages.

Process

I began by creating a GitHub repository to store the files related to the guide, such as a Markdown source file and screenshots. I drafted the guide and tested it in Visual Studio Code to ensure the markup code rendered properly. I followed the Microsoft Manual of Style to ensure my UI documentation and the language I used was user-friendly and well-suited to a beginner-level audience. Then, I downloaded Docusaurus and used it to generate a static site. I relied on Docusaurus's API and user-facing documentation to configure my site.

Documenting the workflows that produced the desired results (e.g. the Markdown source file displaying correctly) helped me debug the code more effectively. Relying on my notes and the knowledge I gained through first-hand experimentation, I was able to pinpoint problematic files, research erroneous code and fixes, and implement changes.

For instance, when I found the site was rendering as expected on my local machine, I surmised the root of the problem of the site not updating with changes I had made lay in GitHub Pages not deploying properly. Therefore, I looked at the file that told GitHub Pages how to build the site and the workflow it was running to do so in order to identify and resolve this issue.

A screenshot of the GitHub Quickstart Guide.

Challenges

The main challenge I faced was configuring my site, as this project is the first time I've used Docusaurus. I relied on Docusaurus's user-facing documentation to build the site. I also relied on my existing knowledge of programming, documentation testing, and code debugging to test the site build and resolve implementation issues.

In addition, I leveraged AI tools like Microsoft Copilot and ChatGPT to accelerate debugging workflows. In doing so, I was able to smoothly deploy my site and even automate deployment via GitHub Pages for seamless testing and publication.

Conclusion

From this project, I bolstered my technical writing skillset by practicing with different tools, namely the Docusaurus static site generator and automating deployment workflows with a CI/CD pipeline via GitHub Pages, as well as strengthening my Markdown and GitHub skills.