my first year as a tech writer

what I wish I'd done

Posted by casey on January 10, 2015

I’ve been in my current position for about a year now. I’m doing what I love so it doesn’t feel like work. I’m challenged, have autonomy, have enough interesting stuff to work on, and so on. The kb is my ward, and I’ve started getting a lot of positive feedback from customers and coworkers.

That being said, there are some things I wish I’d done differently.

How I did it

I came in as the company’s first knowledge base (kb) wrangler. Up until I started, the kb was crowdsourced. The articles weren’t written with an obviously coherent voice, the same actions and items were called by different names, and style standards didn’t exist. It was absolutely beautiful chaos — my dream project. After reading a cross-section of articles I started to pick up on a subtle common voice throughout. It was friendly and helpful. Even if there was a chance you could totally bork everything ever and break the internet if you didn’t follow the directions exactly, the articles were never jerks about it.

Although I was really amped and ready to dive into the kb on my first day, I had to take my time. I created a documentation plan and a laundry list of things I wanted to do to improve our kb.

First up: the style guide and article format/content guidelines

We needed a style guide. Badly. I sat down, checked our parent company’s style guide, read a random sampling of articles, and then pulled our own style guide out of it all. I didn’t copy the parent company’s style guide word-for-word (I will never refer to the internet as the ‘Internet’) — I wanted to preserve the friendly, approachable voice I’d noticed earlier. I wanted to use contractions in introductory text and make ‘drop down’ two words. So I did. I literally wrote the book on how to write stuff for our kb. This kind of style autonomy is a captive tech writer’s wet dream.

The format/content guidelines were easy because I just based them on topic-based authoring standards, but made them super-casual. Not all articles fit into one topic type perfectly. Honestly, this was really hard for me to concede – I really wanted the topic standards to be rigid. However, after reading piles of support tickets, I decided that some task articles needed to be a little more flexible, for the sake of the readers.

Second up: prioritizing existing issues in our project tracker queue

This a semi-embarassing disaster. First, I wasn’t familiar with the app. Second, I didn’t know that whenever I fiddled with a ticket it notified EVERYONE who had ever fiddled with the ticket. I accidentally spammed like, half of the company over the course of a few days before someone was nice enough to give me some best practices pointers. Once I had the app figured out I started knocking out tickets using my sweet-ass style guide. I was in this phase for a while. Tickets rolled in, articles rolled out.

Third up: complete and utterly thorough audit of the kb

This idea floated into my head about six months in. I was starting to get déjà vu. I keep pretty detailed logs of my edits and track time spent on edits and writing, but I felt like I didn’t have a handle on just what was in the kb. So I stopped doing article updates and started a complete content audit. If you’ve never done a content audit on your own content just imagine something you love. Now imagine having to catalog every single detail about that thing. Now multiply it by 1000. It’s exciting at first, but after a while — scratch that, it’s never exciting. It’s tedious, and it’s kind of stressful when tickets are piling up. Content audits are useful, but definitely un-fun.  But when you’re done, it’s pretty magical – You have a giant table of stats about your beloved content kingdom and everything is right with the world again.

How I wish I’d done it

If I could get a do-over of my first year, I’d still do the same stuff, just in a different order.

Start with the content audit

I’d start with the content audit. I’d do this for a few reasons:

  • I’d get to know the hidden voice in the kb, and flesh out the appropriate tones for different article types .
  • I’d become intimately familiar with the 500 different ways someone can write breadcrumb navigation, and could pick a standard that fit our needs best.
  • I’d find deprecated articles that needed to be archived years ago.
  • I'd find some embarassingly-outdated screenshots and videos and kill them.

During the content audit, I would make notes and start a little alpha list.

Create the style guide and alpha list

Once I had that super-sweet mega table of all our articles and content, I’d move on to the style and format guides. After the content audit, I’d have a pretty clear idea of what I did and didn’t want to see in our kb going forward. This way, I could make decisions about style and format based off of what I’d seen working and not working for us.

Tickets and article edits

Finally, I’d start in on the tickets and making article edits. I probably would’ve still spammed half the company, but at least I’d have a better plan.

subscribe to new post notifications