Effective Technical Writing In GitHub

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!

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 \
https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc

chmod 755 /tmp/gh-md-toc

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

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

https://github.com/…/…/paramater_helper.sh#L62-L73

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

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.

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

# full size
![](https://www.dennyzhang.com/wp-content/uploads/denny/wiki_toc.jpg)

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

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

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