Showing posts with label SQL Server Documentation. Show all posts
Showing posts with label SQL Server Documentation. Show all posts

7.7.14

Collaborated Training: What Legacy Will You Leave?

My very first IT job was a bit daunting for me. I really wanted to do my best but I wasn't really sure what they did. One of our supervisors had built a large collection of documentation and a list of our most common issues. It helped so much. That doesn't work as well in the database world. I do document my code and am building documentation on our projects so that everyone has better information. How do I leave behind something that someone else could use beyond simple documentation?

SharePoint

Odd lead in I know. What I plan on doing is simple though. Every day I come across something I've not learned yet but may have some interest in. I plan on creating a folder with the main term listed with an X at the end. This will only signify that I have nothing in that folder yet. When I get time later, I'll go back to each X and see what strikes me as interesting that day.  

Expanding on this idea

At first I'm going to make it simple and keep it to my close friends. The idea would be that anyone can create the folder and put items in each one. Something you didn't even think about may appear suddenly full of information. Something like this could start small scale and end up being a strong repository for multiple people within a few user groups or even beyond. I know we have forums now... but they don't really isolate information for long term use short of searching.

Keeping it clean

I might build it out at the start... but honestly moving stuff around later shouldn't be an issue. At first it will be just a list of items. It'll slowly transform into groups of folders divided by subject. I'm thinking a master legend that's updated weekly/monthly may be good as well. I'm going to set a few requirements on people that upload information that I plan to follow as well. All documents will be labeled BriefInformation-Date-VersionNumber(if applicable). Information within the document should include proper citing. If someone is recording a complete work of someone else, they will need to identify where they got it, when it was obtained and a link back to that location. I should be able to get better ideas of what to write as I slowly build out my personal list of things I don't know.

Negatives

Yes, there is a down side of sorts. If you move on quickly against your will... you may lose control of this. That's where you need to maintain good backups or have an agreement that you can retrieve this before you leave. A worst case scenario is that they may assume they can continue on without you and replace you with a cheaper newer model. That's always the fear of making work look too easy. It's good to declare goals and show accomplishments. There are just simply things you cannot predict. 

Legacy

It's a strong word to use... but hear me out. It's easy to keep a copy of good works for personal use if you keep good backups. Now I'm not saying that you should keep proprietary information... that should have its own folder. Consider what you could gather with this. Most things we learn come from a necessity of some sort. Consider all the things you've learned over the last year or so. How helpful would that have been in one central location for you? Think of all the good an internal WIKI would do? 

I pose this to you. Create this for your own environment and keep a copy for you should you leave. Every new place you go set it up again and keep working on it. How far can this go in a month, year, or even a decade? I've forgotten well more than I can remember. Take all that information you hold and store it mentally offline. This could save you and your co-workers months of effort. Every place you leave will be able to spin the new guy up with ease.  

Final Product

I plan on having something soon to show off for you all. I want to show a working skeleton with instructions and suggestions. I plan on showing price options and alternates for those a bit more cash strapped. I want to have something up and working in the next month that my close friends can demo and work. If anyone has any suggestions, I'll gladly listen to them. I'd even like to eventually get a developer friend or two to work up an app for my phone to hit my site and let me pull up information or write down ideas on the go. If this already exists... throw me a line, I'd love to know.

What do you all think of this idea?

9.6.14

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.