Syed Humza Shah


Engineering leader. Likes coffee. Loves to travel. Runs on a combination of optimism and pragmatism.

Read more about him here.

Lessons I Learned from Writing GitHub Wikis

I’m presently serving my notice period with my current employer. I’ve been the main backend and dev-ops engineer here so there was a lot of information to handover i.e. a lot of stuff to write wikis for.

Here are three things which I actively learned over the course of writing those wikis:

1. Assume no prior knowledge

In the umpteenth proofreading step of my wikis, I realized that I had referenced many internal projects without linking to them or providing practically useful information. This is mainly because my target audience was my current team.

I failed to recognize that these wikis will be read by future employees too i.e. people who will initially have no idea which projects I’m talking about.

Once I realized this, I took a step back to switch gears. I painted pictures that were fuller and made sure that I had properly linked things (especially other repositories or tech pages).

2. Don’t ‘talk’ too much

I’ve had to remind myself many times that a wiki is not a license to be oververbose; for example, while mentioning why a particular step is important, I need not detail how I messed up in the past because I didn’t take said step.

Many times I’ve had to remind myself to stick to the point. An easy way to do this was re-reading the wiki title during proofreading a paragraph and asking myself “If I was reading this wiki, would I care about this info / find it useful?” The answer to that question helped exclude/include text right away.

One of the wikis I had to write were about how I’ve setup Capistrano for a number of the company projects. The code was right there in the config/deploy.rb files - so what was I writing the wiki for? The wiki was there to describe the steps I had taken - the big picture flow of the deployment process.

I took this approach and applied it to all the code-related wikis. A succinct description of logic helps others quickly understand what’s going on; additionally, it lets future devs easily reimpliment things using newer tech.