Skip to content

Instantly share code, notes, and snippets.

@davetron5000

davetron5000/github_repo_of_markdown_files_as_wiki.md

Created December 4, 2015 14:47
Show Gist options
  • Save davetron5000/265d4bf3f8b293580f92 to your computer and use it in GitHub Desktop.
Save davetron5000/265d4bf3f8b293580f92 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
github_repo_of_markdown_files_as_wiki.md

This deserves a longer post

We were having issues with using a "real" wiki, which I think is not uncommon: hard to navigate, changes were opaque and unclear, stale data, hard to search, etc. etc.

So, we adopted a different approach. We now keep all canonical developer documentation as a series of Markdown files in a repo on GitHub. This means that:

  • You can search via GitHub or grep.
  • All changes come with a Pull Request so there can be discussion and notification.
  • We can keep local copies on our computers for offline access.
  • Tweaks and typos can be fixed using GitHub's editor.
  • Longer stuff can be created in your favorite editor, locally.

It's been a year since we created ours and it's been working. It's not perfect, but it's a lot better than Confluence.

The main drawback is the inclusion of diagrams. We've been using a mixture of OmniGraffle (uploading the .graffle file) and yuml.me. Using Gliffy in Confluence is way better, but it's a tradeoff.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment