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.
3. In code-related wikis, cover logic instead of implementation
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.