Using GitHub Wiki for Software Development Documentation (Video)

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.

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.

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

1. From the command line, run git clone <repo wiki url>, as found in the screenshot below.

1. 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

2. In github.com, create a new empty repo with the same name as you used above.

1. Locally, remove the original from your repo by running git remote remove origin.

2. Next, add the new origin by running git remote add origin <new repo url>.

3. Generate a GitHub personal access token with write access to the project in the original repo. See GitHub Docs and the screenshot below.

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

1. 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

2. Add a .circleci directory and a config.yml file in that directory locally.

3. 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 "${GITHUB_EMAIL}"
            git config user.name "${GITHUB_USERNAME}"
            git remote remove origin
            git remote add origin https://${GITHUB_API_KEY}@github.com/<github-username>/<original-repo-wiki.git> > /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.