Best practices for using the wiki

Some of our teammates recommend turning off a repo's Wiki unless you have a proactive use for it. But there are many ways to use a Wiki and use it well.

If you’re using GitHub, you can enable a wiki on every GitHub repo by going to its settings and checking the ‘Wikis’ box under ‘Features.’

Turn the wiki feature on by going to settings and clicking on Wikis under the box labeled 'Features'

What does this get you? Tons! You can now put all the great information that would have made your README way too long and complicated into separate, clear pages. For example, the team uses the wiki for all their “how to do this” work, and catalogues items like decisions on which blogging tags to use across our sites.

This is the 18F site wiki, which catalogs how to use tags on their platforms.

Another really great use for the wiki is to house your product roadmap and user research goals. 18F’s Michelle Hertzfeld is a huge proponent of keeping these documents in the repo with the codebase so they’re easy to find, share and get feedback on.

A screenshot of the roadmap for USEITI website, which is located in a wiki

Tracking user research on GitHub

Speaking of user research, some of our project teams also like to keep their research process and findings in the repo along with the code. This helps keep all project documentation together in one place and also makes sure that we’re not only building in the open, but also researching in the open. This way, team members, and anyone else who is interested, can track the research that went into project decisions.

Naturally, this does not include posting confidential interviews with people or anything else that should not be shared. What it includes are things like:

  • Research plans
  • Interview scripts
  • Summarized research findings

One way to do this is to create an “orphan branch” to keep your research in. An orphan branch is a branch that you name that sits within the repo. Creating an orphan branch lets you have a completely different file structure from the rest of the repo in that branch, and you can put all of your research within that branch, as follows:

  • First, create a new branch under branch:master and label it with a new name. Michelle chose research. (Example)

Create a new branch under branch:master

  • You are now on a branch of the repo, where you can store information.

A screenshot of the research branch

  • Michelle stores information like user research for various sprints in this repo.

Screenshot of user research for Sprint 17

Screenshot of usability tests conducted during Sprint 17