THE SQL Server Blog Spot on the Web

Welcome to - The SQL Server blog spot on the web Sign in | |
in Search

Argenis Fernandez

DBA Best Practices - A Blog Series: Episode 3 - Use a Wiki for Documentation


Retaking on this blog series after an extended hiatus. I hope you will enjoy today’s topic on documentation.

Boring Work? Nope – An Opportunity

One of the often neglected and yet extremely important tasks of any DBA is to document his/her environment. I can certainly relate to those of you who haven’t written a single page of documentation for your environment – I was there before. And I felt bad.

The good news is that documentation doesn’t have to be painful. My friends at Brent Ozar Unlimited recently posted a video on documentation – you can find it in this link – and they touch on that very same subject: There ARE ways to document your environment that will leave you greatly satisfied with the results, and some of you might even enjoy the process. Your manager will love you for it – and you won’t feel bad for the new guy who replaces you when it’s time to move on.

How About Word Documents and Excel Sheets in SharePoint?

Not perfect. Let’s face it. Writing pages and pages of documentation for your database environment (or ANY IT environment) in Word is tiresome. Excel sheets can have tons of information and might be easy to peruse. But no matter how good your formatting is, how many pictures and Visio diagrams you throw at it, you’ll always get the sense that the document you spent days working on will just end up in the SharePoint site and collect dust there. SharePoint can handle changes and versioning for you, if you use it correctly – so that’s a plus. But think about ease of access to the documents – ease of editing. Discussions around it. Even automated updates! Is a SharePoint folder the way to go for that? (Or a UNC path, for those of you without SharePoint?)

An Old Friend Can Work Marvels

You’ve been to WikiPedia. More than once. You know how useful it is, and how, thanks for the built-in search function and Search Engines, easy it is to find information on it.

How about using a wiki engine for your documentation? Can’t picture that in your head? Hear me out: wikis are VERY easy to create, edit and collaborate on – you just click on Edit and away you go. They have built-in version control, discussion pages, categories, lists, and pretty much everything you need to have a versatile documentation site.

Picture this: a wiki page for every environment, listing all the servers that belong to it – and linking to individual wiki pages with tons of information about those servers, including former incident highlights, detailed information about the server (CPUs, RAM, OS Version, SQL Instances, patches, team(s) who own the server, escalation paths for incidents, and much more.

The best part: these pages that have lots of information can be updated via an automated process. WHAT? AUTOMATED DOCUMENTATION YOU SAY? Yes. Think scripts. Scripts that will go over your environments on a regular basis and update information on them in the wiki. Does that sound cool or what? All you need is to understand the capabilities of your wiki engine (think API), and pair it up with your favorite scripting language. For me, it’s a slam-dunk: I’ll use PowerShell to automate the information gathering process, and a wiki engine that runs on SQL Server – I’ll show you a few options in a bit.

Now imagine that you give access to your NOC/Helpdesk to this wiki site: you don’t want them to change anything on it, so you set permissions for read-only access to the site. The benefits would be great: now the NOC has easy access to information on a given server that just alerted, and if you saved notes for that type of alert for that server, instructing Operators to collect certain information before they call you, that can save precious time and help you troubleshoot the issue. You might even let the NOC track incidents on a particular section of the wiki page for that server, so you can figure out if there is a pattern that you need to address.

YMMV on your organization’s needs – but this can be a very valuable tool to keep your business running efficiently. I have worked for teams that relied heavily on Wikis for documentation  - and saw first hand how this greatly improves access to information for our team. How you use it in your environment and how you adapt it to your requirements is entirely up to you – I only wanted to give you a few ideas on how you might put this to your advantage.

Which Wiki Engine Should I Use?

There are TONS of wiki engines out there: WikiPedia has a page (not frequently updated, alas) that lists some of them. Being the SQL Server guy that I am, I’m naturally inclined to use something powered by SQL in the backend. The most widely used wiki engine, developed by the Wikimedia Foundation, is a typical LAMP (Linux/Apache/MySQL/PHP) application. If you have experience with Apache, PHP and MySQL, you should use that. It’s updated very frequently, and it’s got a large community behind it.

Now, if you have SharePoint, you may or may not know that it comes with a wiki engine as well – and that’s detailed here.

Recently I used FlexWiki , which uses SQL Server as a backend. Being a SQL database on the backend, you back it up and keep it safe as the rest of your backups – just don’t use the same servers you’re trying to document to host the wiki engine’s database. If you lose that server, you lost access to the documentation about it.

Unfortunately, FlexWiki isn’t being actively maintained. But look at the list of Wiki software – you’re bound to find something that fits your needs.

No More Excuses – Get To It!

If you have no documentation/poor documentation. Go take care of it, now. Go create and/or reuse scripts that gather information about your environment. Be proactive about it – make sure those scripts get updated. Show your work to your peers and your boss. Feel confident that you have control of your environment, and rock on!

What Are Your Thoughts?

I’d love to hear what you’re doing in your environment as far as documentation goes. Will you leave some comments below? Also, if you feel like giving some feedback on the DBA Best Practices series, I’d appreciate it.

Until next time,


Published Wednesday, February 13, 2013 10:31 AM by Argenis

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS



merrillaldrich said:

Excellent! We are implementing the SharePoint wiki for this and it's a fantastic way to handle ops-type documentation. SharePoint lists in the mix also have great uses (issues log, anyone?) :-). SharePoint obviously has its warts, but it's already present many places and this was a natural fit.

February 13, 2013 1:06 PM

AlexK said:

What happens when something changes and renders your wiki page incorrect?

Documentation gets out of sync with reality all-too-easily, you know...

February 13, 2013 1:22 PM

Jason said:

Thanks Argenis!  I've got a set of Powershell Scripts that I run that dump information into Excel files.  Things like database file locations, DB configuration settings.  Also instance level information such as Configuration information, logins.  Even have sheets that view down to OS level information like Memory, IPs, # of Procs, Cores, etc.  

Right now, I manually run these once or twice a month and upload to a site that the DBA team has access to.  I'll start thinking about using our SharePoint system fuller.

My scripts -

February 13, 2013 1:54 PM

Argenis said:

@Jason that's hilarious, somebody on Twitter was telling me about his own effort to do the same thing, only it saves the information to XML and not Excel. Perhaps we should get a CodePlex project going for this stuff...there's also the work that Chad Miller has done.

February 13, 2013 2:00 PM

Argenis said:

@AlexK - I'm not sure I follow your scenario. If you're careful with your templates and your doc. scripts, you can certainly minimize the likelihood of these "out of sync" issues arising.

February 13, 2013 2:04 PM

Brent Ozar said:

Two other important considerations with this kind of project.

One, you want it to be available when your datacenter is having major problems.  At one company, we had a wiki like this, but the database back end was stored on the SAN.  When we had a SAN outage, we desperately needed to know all of the affected systems, but ... you can see where that's going.

Two, you don't want it to be available to outsiders.  I'm not saying there's a security risk if someone gets a detailed list of IPs, OSs, hardware, etc - good security guys should be able to create that list from scratch quickly anyway - but amongst executives, there's at least the thought that this list is a security risk.  Setting aside the actual risk, the perceived risk is high enough that you probably don't want to just dump it in an insecure cloud or DMZ system in an overreaction to the first problem.

February 14, 2013 8:51 AM

Argenis said:

@Brent - great points, thanks for commenting.

February 14, 2013 10:52 AM

Ty said:

Tiddlywiki is a single HTML file wiki... We recently used it to document a sql application with great success.

February 16, 2013 10:37 AM

Hugo Mendes said:

Great article! A wiki is a great tool to store documentation. We currently use confluence which is easy to use and adopted well within the team - even for colleagues who are not fond of documentation they quickly saw how easy it was to update and then how good the search utility is (searches within uploaded content too).

One downside (to add to Brent's comment) is when we perform our yearly off-site DR test, this wiki server has to be built and recovered first (using printed off DR build documents), before we can recover any of our other servers.

On another note, we've also implemented a script (vbs/wmi) that runs weekly, which grabs all prod server information and writes to  individual server text files, which are then imported into an infrastructure database.  It’s really handy having these [servername_date_config.txt] files at hand.

Scripting really is the only way to ensure that your infrastructure database is up-to-date and correct. Humans are really good at forgetting to update server lists and it only takes one row of incorrect data to put the whole database integrity at stake prompting your manager to assign a ‘please check and update our entire server inventory table’ task to your name.

February 18, 2013 5:19 AM

Leave a Comment

Privacy Statement