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 efforts goes into maintaining a GitHub page.
As a late fanboy of Atlassian Confluence, my new preference is now GitHub wiki. Enclosed are tips for how to write effective documentation in GitHub.
Permanent Link: http://dennyzhang.com/github_wiki
Tons of discussions for "wiki vs. Confluence" are happening on the Internet. Here, we just assume you're in favor of wiki, which GitHub is using. Bitbucket and GitHub are very similar, so the experiences illustrated in this article should apply to both nicely.
Tips: Manage GitHub Wiki in a Git Way
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!
Tips: Insert Table of Contents for Lengthy Pages
For large pages with many sections and bullet points, we'd better insert a TOC (Table Of Contents). Currently, GitHub doesn't have built-in support, but it can be done easily by a third party 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
Tips: Generate Links 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 next time you need to refer a code block to your colleagues.
Tips: Generate Links to Compare Two Revisions
Revision comparison can be done easily in GitHub GUI. For example: https://github.com/.../.../compare/sha1...sha2.
Comparison between branches and tags are also supported like this.
Tips: Resize Images in Wiki Pages
Resize big images to better fit wiki pages. Paste below lines to your wiki, you will see the difference.
# full size !(http://www.dennyzhang.com/wp-content/uploads/denny/wiki_toc.jpg) # resize image to smaller <img src="http://www.dennyzhang.com/wp-content/uploads/denny/wiki_toc.jpg" width="100">
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
Like our blog posts? Discuss with us on LinkedIn, Wechat, or Newsletter.