Using GitHub Wiki for Software Development Documentation (Video)

Learn the pros and cons of using GitHub Wikis vs README files in your code, then walk through a GitHub Wiki tutorial.

In software development, creating good documentation is critical. While there are documentation services like docsify, according to my experience, the two most common choices for storing technical documentation are storing markdown files in a “docs” folder within your project’s repository and utilizing a Wiki. More specifically when using GitHub, utilizing the GitHub Wiki feature.

Each of these choices has pros and cons.

README files in your code

Pros	Cons
You can track the work that’s being done and the documentation for that work in one place.	No separation of concerns.
Presents a quick and simple way for other users to learn more about your work.	Can become difficult to navigate.
Allows for peer review.

GitHub Wikis

Pros	Cons
Uses the same Markdown language as the readme files.	No way to create a pull request, meaning you need to create a way to peer-review. This can lead to incomplete or incorrect documentation.
Allows for easier navigation than just a README.
Separation of concerns between code and documentation but still connected to the same repository.

One way of mitigating the GitHub Wiki approach’s cons is to create a second repository that controls the wiki of the project’s repo. GitHub wikis can be pulled down to edit locally, giving us the opportunity to push to that repo. By setting up a second source to control the wiki, we introduce the option of enforcing pull requests on our documentation. This solution does have its own cons though, so it’s important to figure out what will work best for you and your team.

Linking up a second repo to your wiki

Pros	Cons
All the pros of READMEs.	A little bit of setup.
All the Pros of Wiki’s.	There is now a second repo to keep track of (more or less of a con, depending on the team).

Setting Things Up

I’ll be utilizing circleci for syncing our repos due to my familiarity with it and its ease of use. You can also use any hosted continuous integration service, such as Travis CI. Before beginning, you or your organization will need to have signed up for circleci or your service of choice. Wikis can be forked and pulled down to edit locally in the same way the repository can. You can clone from the “wiki” tab of your repo. The following steps and accompanying video should get you on your way to this solution.

Steps

From the command line, run git clone , as found in the screenshot below.

Once it is cloned locally, rename the project. I suggest replacing the “repo.wiki” to “-wiki.”
- e.g. mv example-project.wiki example-project-wiki
In github.com, create a new empty repo with the same name as you used above.

Locally, remove the original from your repo by running git remote remove origin .
Next, add the new origin by running git remote add origin .
Generate a GitHub personal access token with write access to the project in the original repo. See GitHub Docs and the screenshot below.

Add your new repo as a circleci project, in the circleci dashboard. See circleci Docs.

In your circleci project, add the following environment variables:
- GITHUB_EMAIL : The GitHub account email you created the personal access token with.
- GITHUB_USERNAME : The GitHub account username you created the personal access token with.
- GITHUB_API_KEY : The personal access token from GitHub
Add a .circleci directory and a config.yml file in that directory locally.
Fill the config with the following:

version: 2.1 description: Automatically build and push to your GitHub Repo Wiki jobs: build: docker: - image: circleci/node steps: - checkout - run: name: Push Wiki To Project Wiki command: | git config user.email "$" git config user.name "$" git remote remove origin git remote add origin https://$@github.com// > /dev/null 2>&1 git push origin master > /dev/null 2>&1 workflows: main: jobs: - build: filters: branches: only: master

Note that any output generated by the command is redirected to /dev/null so that secrets never show up in the build log. You can see this config as an example.

Final Thoughts

As we’ve seen, using circleci makes it pretty easy to eliminate some of the downsides of using GitHub Wikis for team documentation. I hope you’ve found this helpful and that you can use this on your team’s next project.

Sparkbox’s Development Capabilities Assessment

Struggle to deliver quality software sustainably for the business? Give your development organization research-backed direction on improving practices. Simply answer a few questions to generate a customized, confidential report addressing your challenges.