Documentation: What Can We Document?

          I think I'd like to do a small short series on documentation. I personally love documentation. I honestly think most of us like documentation, we just hate writing it. There are quite a few excuses I've heard against writing it.

1. I don't have time to document as I code.
2. Changes need to be in place now, I can't waste time documenting.
3. This isn't my code.
4. There's too much to document now.
5. We plan on deprecating this system in the next year or two.
6. Everyone's already familiar with this system.

It doesn't honestly take much time to add some documentation. We don't need everything to have the letterhead, pretty backgrounds, screenshots and instructions for every single line. Here are a few examples of fast commenting.

-- in T-SQL adding two dashes allows your comment to sit right next to or under your code. This is great for explaining a bit toggle or what options exist in a SP.

/*

In T-SQL, adding the /* at the start of a comment will comment anything out until you end with the */, no matter how many lines deep it is. Great for revisions, modification explanations, author credit, date created and many more uses.

*/

in SSIS you can right click the open area and insert an annotation. you can set signs such as, "Don't run this step without running the previous step." and many other variations. 

You can even create your documentation in Excel or Word for larger projects or even to document what tables and SP's a certain job needs. 

The one thing I'd want documented more than any of these other things would be changes. A change log for the network, Domain Controllers, Server, SQL instance, tables, stored procedures, just about anything. A simple file share with folders for each group would be useful for a change log. Share Point may be a better target if you have that in your environment. File names could be as simple as Servername.doc. 

/**************************************************************

Admin: John Doe

Change: Modified Max RAM to 177152.

Reason: Leaving 10% to the OS and other functions.

Date: 6/9/2014

**************************************************************/

/**************************************************************

Admin: Jane Doe

Change: Modified Remote Admin Connections to 1

Reason: Ability to remote the DAC when the server is having issues. Temporary change while troubleshooting Database issues related to Ticket #0003425552

Date: 4/21/2014

**************************************************************/

A year later we may see a setting, wonder why or who changed it and now we have a searchable document to answer these questions.