Effective Technical Writing In GitHub

Delivering short and precise documents quickly is a key asset for DevOps. Nowdays, hosting code in GitHub is not only fancy but also overwhelming. Consequently more and more documentation effort goes to GitHub.

As a late fanboy of Atlassian Confluence, I also make my preference in GitHub wiki now. Enclosed are tips for how to do effective documentation in GitHub.


Tons of discussions for “wiki VS Confluence” are ongoing in the Internet. Here we just assume you’re in favor of wiki, which GitHub is using. Bitbucket and GitHub are very similar. Experience illustrated in this article should apply to them both nicely.

1.1 Tips: Manage GitHub wiki in a GIT way.

GitHub clone WIKI

Usually we edit wiki in GitHub website. The most charming point of GitHub wiki is everything is stored in a git repo. We can git clone all pages, do the editing offline and push the change later. You get everything locally as plain text. As a GNUS guy or even an emacs user, you certainly know the difference and value. Right? Furthermore, compared to Atlassian Confluence, data backup is much easier and it’s 100% free and reliable!

1.2 Tips: Insert table of contents for lengthy pages.

WIKI Table Of Content

For large pages with many sections and bullet points, we’d better insert TOC (Table Of Contents). Currently GitHub doesn’t have built-in support. It can be done easily by a third part tool, gh-md-toc.

wget -O /tmp/gh-md-toc \

chmod 755 /tmp/gh-md-toc

# generate TOC for a wiki page
bash /tmp/gh-md-toc ./test.md

1.3 Tips: Generate link for a block of code.

Linus Torvalds said: Talk is cheap, show me the code. One step further, show me the code link.


Compose your link nex time, when you need to refer a code block to your colleagues.

1.4 Tips: Generate link for the comparison of two revision.

Revision comparison can be done easily in GitHub GUI. Example: https://github.com/…/…/compare/sha1…sha2.

Comparison between branches and tags are also supported like this.

GitHub comparison

1.5 Tips: Resize image in wiki pages.

Resize big images to better fit wiki pages. Paste below lines to your wiki, you will see the difference.

# full size

# resize image to smaller
<img src="https://www.dennyzhang.com/wp-content/uploads/denny/wiki_toc.jpg" width="100">

1.6 Tips: Export Github Wiki To PDF.

You may want to export one private wiki to a user-friendly PDF. Try pandoc, a universal document converter.

# Install pandoc
sudo apt-get install -y pandoc

# brew install pandoc

# Sample Conversion
pandoc -f markdown_github -o output.pdf ./input.md

More Reading: Avoid Unnecessary Communication Of TOI


PRs Welcome

Blog URL: https://www.dennyzhang.com/github_wiki

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.