Posts Tagged 'Development Support'

April 27, 2015

Good Documentation: A How-to Guide

As part of my job in Development Support, I write internal technical documentation for employee use only. My department is also the last line of support before a developer is called in for customer support issues, so we manage a lot of the troubleshooting documentation. Some of the documentation I write and use is designed for internal use for my position, but some of it is troubleshooting documents for other job positions within the company. I have a few guidelines that I use to improve the quality of my documentation. These are by no means definitive, but they’re some helpful tips that I’ve picked up over the years.


I’m sure everyone has met the frustration of reading a long-winded sentence that should have been three separate sentences. Keeping your sentences as short as possible helps ensure that your advice won’t go in one ear and out the other. If you can write things in a simpler way, you should do so. The goal of your documentation is to make your readers smarter.

Avoid phrasing things in a confusing way. A good example of this is how you employ parentheses. Sometimes it is necessary to use them to convey important beneficial tidbits to your readers. If you write something with parentheses in it, and you can’t read it out loud without it sounding confusing, try to re-word it, or run it by someone else.

Good: It should have "limited connectivity" (the computer icon with the exclamation point) or "active" status (the green checkmark) and NOT "retired" (the red X).
Bad: It should have the icon “limited connectivity” (basically the computer icon with the exclamation point that appears in the list) (you can see the “limited connectivity” text if you hover over it) or “active” (the green checkmark) status and NOT the red “retired” X icon.

Ideally, you should use the same formatting for all of your documentation. At the very least, you should make your formatting consistent within your document. All of our transaction troubleshooting documentation at SoftLayer uses a standardized error formatting that is consistent and easy to read. Sometimes it might be necessary to break the convention if readability is improved. For example: Collapsible menus make it hard to search the entire page using ctrl+F, but very often, it makes things more difficult.

And finally, if people continually have a slew of questions, it’s probably time to revise your documentation and make it clearer. If it’s too complex, break it down into simpler terms. Add more examples to help clarify things so that it makes sense to your end reader.


Use bullet points or numbered lists when listing things instead of a paragraph block. I mention this because good formatting saves man-hours. There’s a difference between one person having to search a document for five minutes, versus 100 people having to search a document for five minutes each. That’s over eight man-hours lost. Bullet points are much faster to skim through when you are looking for something specific in the middle of a page somewhere. Avoid the “TL;DR” effect and don’t send your readers a wall of text.

Avoid superfluous information. If you have extra information beyond what is necessary, it can have an adverse effect on your readers. Your document may be the first your readers have read on your topic, so don’t overload them with too much information.

Don’t create duplicate information. If your documentation source is electronic, keep your documentation from repeating information, and just link to it in a central location. If you have the same information in five different places, you’ll have to update it in five different places if something changes.

Break up longer documents into smaller, logical sections. Organize your information first. Figure out headings and main points. If your page seems too long, try to break it down into smaller sections. For example, you might want to separate a troubleshooting section from the product information section. If your troubleshooting section grows too large, consider moving it to its own page.


Don’t make assumptions about what the users already know. If it wasn’t covered in your basic training when you were hired, consider adding it to the documentation. This is especially important when you are documenting things for your own job position. Don’t leave out important details just because you can remember them offhand. You’re doing yourself a favor as well. Six months from now, you may need to use your documentation and you may not remember those details.

Bad:SSH to the image server and delete the offending RGX folder.
Good:SSH to the image server (imageserver.mycompany.local), and run ls -al /dev/rgx_files/ | grep blah to find the offending RGX folder and then use rm -rf /dev/rgx_files/<folder> to delete it.

Make sure your documentation covers as much ground as possible. Cover every error and every possible scenario that you can think of. Collaborate with other people to identify any areas you may have missed.

Account for errors. Error messages often give very helpful information. The error might be as straightforward as “Error: You have entered an unsupported character: ‘$.’” Make sure to document the cause and fix for it in detail. If there are unsupported characters, it might be a good idea to provide a list of unsupported characters.

If something is confusing, provide a good example. It’s usually pretty easy to identify the pain points—the things you struggle with are probably going to be difficult for your readers as well. Sometimes things can be explained better in an example than they can in a lengthy paragraph. If you were documenting a command, it might be worthwhile to provide a good example first and then break it down and explain it in detail. Images can also be very helpful in getting your point across. In documenting user interfaces, an image can be a much better choice than words. Draw red boxes or arrows to guide the reader on the procedure.


October 10, 2012

On-Call for Dev Support AND a New Baby

I began working at SoftLayer in May of 2010 as a customer support administrator. When I signed on, I was issued a BlackBerry to help me follow tickets and answer questions from my coworkers when I was out of the office. In August of 2011, that sparingly used BlackBerry started getting a lot more use. I became a systems engineer in development support, and I was tasked to provide first-tier support for development-related escalations, and I joined the on-call rotation.

In the Dev Support group, each systems engineer works a seven-day period each month as the on-call engineer to monitor and respond to off-hours issues. I enjoy tackling challenging problems, and my Blackberry became an integral tool in keeping me connected and alerting me to new escalations. To give you an idea of what kinds of issues get escalated to development support, let me walk you through one particularly busy on-call night:

I leave the office and get home just in time to receive a call about an escalation. An automated transaction is throwing an error, and I need to check it out. I unload my things, VPN into the SoftLayer network and begin investigating. I find the fix and I get it implemented. I go about my evening, and before I get in bed, I make sure my BlackBerry is set to alert me if a call comes in the middle of the night. Escalations to development support typically slow down after around 11 p.m., but with international presences in Amsterdam and Singapore, it's always good to be ready for a call 2:30 a.m. to make sure their issues are resolved with the same speed as issues found in the middle of the day in one of our US facilities.

Little did I know, my SoftLayer experience was actually preparing me for a different kind of "on-call" rotation ... One that's 24x7x365.

In June 2012, my wife and I adopted an infant from El Paso, Texas. We'd been trying to adopt for almost two years, and through lots of patience and persistence, we were finally selected to be the parents of a brand new baby boy. When we brought him home, he woke up every 3 hours for his feeding, and my on-call work experience paid off. I didn't have a problem waking up when it was my turn to feed him, and once he was fed, I hopped back in bed to get back to sleep. After taking a little time off to spend with the new baby, I returned to my job, and that first week back was also my turn on the on-call rotation.

The first night of that week, I got a 1 a.m. call from Amsterdam to check out a cloud template transfer that was stuck, and I got that resolved quickly. About 30 minutes later, our son cried because he was hungry, so I volunteered to get up and feed him. After 45 minutes, he'd eaten and fallen asleep again, so I went back to bed. An hour later, I got a call from our San Jose to investigate a cloud reload transaction that was stalling with an error. I worked that escalation and made it back to bed. An hour and a half later, the little baby was hungry again. My wife graciously took the feeding responsibilities this time, and I tried to get back to sleep after waking up to the baby's cries. About an hour later, another data center had an issue for me to investigate. At this point, I was red-eyed and very sleepy. When my teammates got up the next morning, they generously took the on-call phone number so I could try to get some rest.

This pattern continued for the next six days. By the end of that first week, I got a call from work at about 3 a.m., and I picked up the Baby Monitor from the night stand and answered, "Dev support, this is Greg." My wife just laughed at me.

I've come to realize that being on-call for a baby is a lot more difficult than being on-call for development support. In dev support, I can usually documentation on how to resolve a given issue. I can search my email for the same error or behavior, and my coworkers are faithful to document how they resolve any unique issues they come across. If I get to a point where I need help, I can enlist the assistance of an SME/Developer that commonly works on a given piece of code. When you're on-call with a baby, all the documentation in the world won't help you get your newborn to stop crying faster, you don't get any clear "error messages" to guide you to the most effective response, and you can't pass the baby off to another person if you can't figure out what's wrong.

And when you're on-call for development support, you get some much-needed rest and relaxation after your seven days of work. When you're on-call for a new baby, you've got at least a few months of duty before you're sleeping through the night.

As I look back at those long nights early on, I laugh and appreciate important things in my life: My wife, my son, my job and my coworkers.

– Greg

Subscribe to development-support