Software

Five tips for creating useful client documentation

Incomplete or obsolete documentation is scarcely better than no documentation at all. But by following these tips, you'll have the information you need where and when you need it.

Documentation is one of the single most important tools you can have for the job. It's also one of the easiest aspects of the job. But when it's not there, the job can be an absolute nightmare. As a consultant, you have to make a choice: Do you rely on the client to retain documentation or do you retain it yourself? If you retain the documentation, a few simple steps will help ensure that it's as efficient and useful as possible.

1: Be consistent

This one is crucial, and you need to put it into place at the very start. Instead of being random or chaotic with documentation, create one or more templates for documentation and use them religiously. I prefer creating one document for important credentials and separate documents for network mapping, contracts, misc notes, and contact information. Even within those different documents, I always make sure I follow through with consistency; otherwise, I'll be digging around for the information, which is nothing but a waste of time.

2: Use .txt instead of .doc

You never know what you're going to have available to view your documentation. So instead of using .doc (or .docx) files to create the documentation, use .txt files so you can view them on nearly anything. This will also make your life easier if your documentation is on a network and you don't want to count on Microsoft Word to be consistent and reliable opening those documents. Besides, a .txt viewer is going to open more quickly than Word ,which is especially important when you're in a serious time crunch.

3: Use Dropbox

You're not always going to be sitting at the machine housing your documentation. Even if you place your documentation on a server within your network, you don't want to have to jump through the hoops of RDP'ing into your network just to view client documentation. Instead, use a tool like Dropbox to keep your documentation synced on a machine you carry around. (You can also access your Dropbox account from anywhere.) Just make sure the account is secured with a challenging password!

4: Separate clients into folders

Don't have just a single folder containing a bunch of documents for clients. If you manage your documentation this way, you'll spend a lot of time searching for the information you need.Use a little common sense with your organization and separate clients into individual subfolders under the main Documentation folder. This way, getting to that particular client documentation will be fast and easy.

5: Update

Don't let documentation updates get out of hand. If you forget once, you'll forget again. And nothing is worse than changing a domain administrator account password, not documenting it, and then needing it. As soon as you change an important piece of a client's network or credentials, change it in the documentation. Do NOT depend upon your memory for this. You never know when something is going to sidetrack you. Not only will this cause you an enormous headache, it will also make you look bad in front of your clients. Make a habit of updating documentation quickly (even on the job site).

Documentation upsides

Remember, your clients are your bread and butter. When you work with less-than-efficient speed, you're costing them money they probably don't want to spend. By making your documentation as efficient as possible, you save yourself time and headaches and (in the end) your clients' money. We all know, saving clients some money is one of the best ways to ensure client retention.

About

Jack Wallen is an award-winning writer for TechRepublic and Linux.com. He’s an avid promoter of open source and the voice of The Android Expert. For more news about Jack Wallen, visit his website getjackd.net.

9 comments
blombach
blombach

I use TextPad when I am in a hurry and only need to jot down notes, but I disagree that TXT files are a better choice for customer documentation. The best documentation is formatted with adequate whitespace, font styles, footnotes, headers, etc. Sure, Word might take 1 or 2 second longer to load, but in seasoned hands Word becomes a time saver. Also, there is no reason to use the .DOC format anymore (upgrade already!) because the compressed XML used in .DOCX is super fast. I agree with some of the other comments, I usually print to PDF and supply that version to the customer, for portability more than anything else.

jymkch
jymkch

I use bento on my iPad to file absolutely everything, including pics. I may try Omnigraffle for network maps and as far as i know if you have the app on the iPad you could open and edit those files there too.

lancekephart
lancekephart

We separate our clients into folders, but we use an excel spreadsheet. If a client has more than one site, then each site gets it's own tab (includes LAN IP scheme and WAN IP info), but it's still all located in the same spreadsheet. We can also add images of their wiring closets and network hardware, which helps with troubleshooting when you have to walk someone through rebooting their modem or firewall. If a site has several servers (or several sites), then we typically will list out all of their servers and IP addresses, as well as if they have DRACs installed and it's IP address. If we are going to be making any major changes, such as new hardware (server, firewall, modem) or WAN IP change, then we'll print out a hardcopy to take with us, then update our document when we get back to the office. In a pinch, we each have a gmail account and can use Google Docs to document the info, then update their regular documentation when we get a chance. Worst case, type out an email on the smartphone - painful if there is a lot to document, but works when you go out the door without a laptop, a document, or coffee...

biancaluna
biancaluna

I am sure you meant you are updating documentation within your change control process, is that right? And that memory has limited to do with that, but you are using some form of process? I have another tip - undertake some sort of writing course to avoid the geek speek gobbledygook that I have seen in many pieces of documentation. Version control properly. The .txt file issue appears to be somewhat of a bias, it is your job to produce useable documentation then you should use industry tools such as visio and PDFs to ensure you can include images. Securing the documentation you produce is never an afterthought - and needs to comply with corporate policies, legislation or the quality standards applied in your client's environment. To me this article misses the boat a bit, and contains a few statements that I would expect out of a graduate, not a seasoned consultant.

redventura
redventura

Rarely documented is Notepad's auto-timestamp feature. Sure, pressing F5 is a quick and easy to add a date / timestamp to the file. Though add ".LOG" (without quotes) as the first line of the text file, and Notepad will automatically add the date and time stamp as a new line every time you open the file. This not only helps for documenting, but also for tracking your time while at a clients'.

TAPhilo
TAPhilo

The only issue with text only files that I have ever seen is that you have to WRITE more descriptively since now you have eliminated the use of images when explaining item. Thus, it takes longer to write and you have to ALWAYS assume the person reading it has the bare minimum basde knowledge of whatever needs fixing and the step by step has to be VERY precise. You become a very highly paid technical writer of a very complex solution. I document using MS Word (or VISIO is some cases) convert to PDF and then post. I always page number (page x of y) and auto-date the doc so that we always know at a glance if that if two are seen we can tell what is the latest version. Putting in the page x of y also lets a person know how long the instruction set is so they have the expectation / time factor knowledge which makes them work better. Like the . . . . . . ant trail when installing so you know how long it is going to take.

gechurch
gechurch

Yeah - with great tools like remote desktop, phone email and google docs there really is no need to plain text documentation. I have a problem with your last comment though; no IT pro should ever leave the office without at least a coffee and a laptop or documentation!

gechurch
gechurch

I agree, especially given that the article talks about documenting passwords. I agree with you - Word + Visio to PDF is a nice mix. I use offline files instead of Dropbox, and if I'm ever on a machine without Word or Acrobat I just remote in to our terminal server. The worst case scenario is that no machine around has an Internet link, in which case I have to turn on my laptop or connect in using my phone. Give me that over plain text documentation any day.

OurITLady
OurITLady

Whenever I'm documenting anything that's more than a couple of steps, or that I may expect a non-tech or non-expert to have to follow I always add screenshots to each of the stages for clarity. That way the person trying to follow the documentation knows exactly what they should be seeing at what stage and which field of the dialog box they're supposed to type the entry in. Admittedly if you are dealing with non-windows OS then the .doc format may not be the most appropriate, but you should know that from the topic of the documentation and be able to save in a format that can be opened on the relevant system.