Documentation for the client's benefit

Date June 23, 2010

If I've said it once, I've said it, oh, 5 times now, Documentation Shall Set You Free. And I really mean it. But does it have the ability to free others? Of course!

My company has been doing well, and getting some large clients. That is great, but these large clients also place different requirements on us than the smaller ones that we used to deal with. For one thing, they ask questions. Lots of questions, actually.

In the past two months, I've probably completed 5 questionnaires of at least 50 questions each, all wanting to know about internal policies, procedures, security controls, etc. Basically, they want to know that we run a tight ship, and that we do things like think about disaster recovery, security, and so on. I can't say that I blame them for asking, but it's damned irritating to constantly answer the same questions again and again (sometimes repeatedly in the same document!). Plus, there are the occasional questions that just boggle your mind. "Do you use electronic systems?" And this was in an Excel spreadsheet!

Rather than just answer each question with an appropriate link to a blog entry I've written, my boss thought it would be good to proactively offer a document that covers the infrastructure's design, security, documentation status, etc, the thought being that it would answer most of their questions out of hand.

Since I like documenting things, I'm in favor of it, but I do have to wonder what kind of traction it's going to get with our clients.

"Answer these questions."
"Here's a document explaining everything."
"Great. Get those answers to us ASAP."

Anyway, do any of you have experience with client expectations like this? I'd love to hear about it. Thanks!

  • http://www.protocolostomy.com Brian K. Jones

    Good post, Matt. I agree that even if you offer a document proactively, those clients are still going to want those questionnaires back. I suspect it's not reviewed by an employee of your client, but rather their insurance or legal representative that probably require them to have that on file somewhere.

    As for documentation, I think about that a lot as you know. The conclusion I've come to after working with lots of super smart people who *don't* document as they should is that it's not a matter of convincing anyone that it's the right thing to do. Rather, it's a matter of giving people tools and showing them how to use them. As it turns out, there is no tool that works in every environment for every need, so this becomes something of a difficult task.

    It also illustrates a rare area where I believe an IT team is perhaps less capable of making a decision than management, even though the solution almost certainly involves technology. Why? Because every technical person you talk to has wildly different notions of what documentation should be, how it should be created, how it should be accessed, how it should be archived, updated and maintained. While some are happy to work in a browser-based environment for all of those things, some insist that if it's not editable in vi or emacs, it's no good. Getting everyone on the same page is a challenge.

    Do-everything tools where people can all have it their way are cumbersome in my experience, and although they try to be all-singing-all-dancing, doing so inevitably (and maybe ironically) involves compromises.

    Anyway, maybe I should start my own blog post. I really just wanted to say I enjoy your writing :)

  • Ryan K

    Matt,
    Haven't posted for awhile, but saw this and had to comment. Recently I have been moving from Sysadmin/engineer into a Security engineer role, specifically focusing on Customer audits (we get dozens a year, some of them over 2k questions!). And you are 100% right about that document. Every questionnaire and every onsite auditor will have different question formats and they don't want to do the work of inputting the answers from your sheet. Saying that though, if you can get all of your answers on one piece on one document for you, it makes it much easier when you start having to answer these questionnaires, as you don't have to go looking through policies and standards to get the answers out. You have them all prepped and ready to go to plug into place. Here is one of the ultimate questionnaires you can get (and if you can answer all the questions, you are set for almost all other audits or questionnaires) the BITS SIG http://www.tennx.net/ABR/Outdated/SIGv3_1.xls

  • John M

    I use a Magic 8 Ball for most questionnaires... :-)

    Seriously, it seems every organization (and departments in the same organization, but I digress...) has its own legal requirements for their audits.

    Creating a Database/Wiki Page/Cheat Sheet with commonly asked questions relating to your own organization does help though.

  • Pingback: Tweets that mention Documentation for the client’s benefit | Standalone Sysadmin -- Topsy.com()

  • http://www.standalone-sysadmin.com Matt Simmons

    @Brian

    Thanks! I'm glad you like reading it. I like writing it! You definitely should do a blog post. Just drop me a line when it goes live and I'll link to it. And again, thanks!

    @Ryan
    Thanks for the comment and the link. I agree, it'll be good to enumerate the answers beforehand anyway, just so we can copy/paste to make things faster.

    @John
    Nice! That's an advancement from chicken bones ;-) I hadn't thought of putting the answers in the wiki, but that's a good idea, thanks!

  • http://blog.luxem.org Doug Luxem

    Matt, I also work for a SaaS provider and we field this questionnaires on a weekly or more frequent basis. It amazing how much variation there is between different companies' requirements too.

    The solution for us though is to go through a SAS 70 audit. The Type 1 audit basically is a snapshot of the controls (security, change management, etc) you have in place. The Type 2 audit is more meaningful in that outside auditors will actually verify that you followed your controls over a period of time. These audit reports can then be provided to your customers to answer most of their questions.

    One difficult part is that SAS 70 does not specify which controls are necessary. Although the auditors can help with this, it is best to keep a record of all of the questionnaires you have received which essentially gives you a starting point setting up controls.

    Other routes you could go are ISO 20000/27000 certification which may overlap with SAS 70 requirements anyway.

  • http://itforme.wordpress.com/ Sketchy

    A colleague of mine runs into this quite often (more so than myself, as he does consulting, while I'm at one organization). In both of our cases, we've found that much of the time, the ability to document this type of thing relies heavily on the tools that really lend themselves to it. Wikis can be great for this. But in my opinion, an even better solution is to use OneNote. Whether it's to document topology, infrastructure, and existing configurations for various aspects of a network, or for use with as-built notes for internal IT documentation, nothing beats it. I wrote about my experiences, and how it changed how I work. Here's the link.

    http://itforme.wordpress.com/2010/04/06/using-onenote-in-it/

  • Anthony

    We get this all the time. As you posted and others have said, they don't want to read what you've written - they just want you to fill in their form so that they can say they got it and file it in a drawer somewhere.

    The problem is, since these are "clients/customers" and not service providers, you can't be nasty with them and tell them to read your document and get off your case.

    However, your role as Systems Administrator is to create/maintain the policy and procedures that they are asking about and provide documentation about those things. There's no reason you can't be nasty with the sales reps and customer reps who dump the form on your desk and say fill it out. Tell them you've already documented everything they need to know about the company that THEY are working for and that THEY should be able to answer the questions themselves.

    Then if you want to be nice you can write your documentation so that includes some of the most common questions you get so they aren't completely lost.

    Frankly it's in their own best interest to know how your company works - and they will look a lot smarter in the clients eyes if they can answer those questions in person and by themselves.

  • Chris Wilson

    Hey Matt,

    I'm not sure how it works in the US, but in the UK we have 'ISO' standards which if adhered to (i.e we have a shiny certificate on the wall) is a very quick way for 'clients' to check we meet certain standards, it saves us filling out paperwork for every new client and is often a requirement in sales bids.

    A good example (and one we're dealing with at the moment) is ISO 27001 (http://en.wikipedia.org/wiki/ISO_27001).