Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Effective Technical Writing in GitHub

DZone's Guide to

Effective Technical Writing in GitHub

Documentation in GitHub wiki pages is becoming more and more important. Here are some tips to make it more readable for all involved.

· DevOps Zone
Free Resource

“Automated Testing: The Glue That Holds DevOps Together” to learn about the key role automated testing plays in a DevOps workflow, brought to you in partnership with Sauce Labs.

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.

github_wiki.pngPermanent 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

github_clone_wiki.png

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

wiki_toc.jpg

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."

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

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.

github_comparison.png

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.

Learn about the importance of automated testing as part of a healthy DevOps practice, brought to you in partnership with Sauce Labs.

Topics:
github ,documentation ,devops

Published at DZone with permission of Denny Zhang, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}