T-SQL and PowerShell Documentation With Gists

By: Tim Smith   |   Comments   |   Related: More > DBA Best Practices

Problem

One challenge developers and DBAs face is documenting specific processes, troubleshooting techniques, and standard solutions for errors. Most developers and DBAs have their own starting points and preferred approaches; for instance, most DBAs I've worked with prefer to use the SSMS interface, while I prefer scripts. This leads each person to often develop or create their own documentation for problem solving, especially when one server or environment may face the same problem as another server or environment while requiring a completely different set of solutions. This can create problems when developers or DBAs may not have access to word processing tools, or may not have access to where they saved their documentation. For instance, if we can't access our computer and we're facing an issue, it's nice to have a back-up place on the web to go to.

I've run into three "could-have-been-a-disaster" issues had it not been for having a back-up location for documentation:

1. I could not obtain access to a drive where I had an important Word file saved.
2. My computer crashed on vacation when a trader needed an updated query.
3. The monitoring machine was offline, while the machine with an issue that needed the solution was not.

In this tip, we look at a free web-based tool that can be used to store your documentation.

Solution

GitHub gists allow for private documentation (provided links aren't directly shared) without any costs and are built in a manner that represents developers and DBAs unlike many word processing tools, the latter which sometimes add special characters that are unrecognized by compilers.

GitHub offers a free documentation tool through the web called gists and these can help developers create quick documentation with step through code for solving some problems, documenting quick how-tos, or keeping an index of scripts. There are many features that I like with gists, especially considering that I may have code in either T-SQL or PowerShell (most of the time) and this won't disrupt a gist, as I can store both in the same file. For the sake of this tip, I'll show how to use markdown files to build quick documentation.

To create one, we give a description and choose any file name and end the file name with .md as shown in the example below.

Saving Code with GitHub Gists

If we want to save multi-line code in our mark down file, we can use the below syntax. Multi line code goes between the opening and closing ```.

```
Select
  ColumnOne
  , ColumnTwo
FROM TSQLCodeBlock
```

```
Function Execute-PowerShell {
  Param(
    [string]$PowerShell
  )
  Process
  {
    Write-Host "$PowerShell code block"
  }
}
```

Both of these will appear as code blocks on our markdown file as shown below:

This is very useful when scrolling through a quick how to and copying code to solve a problem, especially if the code is something you must manually call each time you experience the issue. Combine this with CTRL-F (find) and you can quickly get the block of code you need for a particular issue.

Creating a To Do list with GitHub Gists

Adding a to-do helps when you need to remember a further problem to solve, but you're in the middle of solving a different problem. For instance, if I want to automate updating statistics, but I first want to get the latest update of statistics, adding a later to do helps, as it's easy to forget. In addition, I can keep to-dos in the same gist so that they relate to each other. A to-do for indexing would not be in the same gist as a to-do for availability groups. To create a to-do list:

This is a to do list:
- [ ] This is not done.
- [ ] This is not done.
- [x] This is done

Below is what this will look like. Because it's a markdown file, we can check a to do item even outside of editing the file (if I were to click on of the unchecked boxes, it would become checked):

The ability to check and un-check items becomes very handy when we have tasks like migrating an old edition of SQL Server to a newer edition of SQL Server and we have a step-by-step list we cross off. Once we're done, we can go back and uncheck all the items for the next time we have to migrate databases (or another task like it). The same is true for debugging; problems have a tendency to re-appear and it's good to remind yourself what you did last time. I probably save 10 or more hours a week using gists because I can easily hop to the gist I need for a similar problem or design approach. This leads me to another helpful feature.

Linking with GitHub Gists

This is very helpful to link to other gists, code, or documentation about a particular problem or design. The syntax for linking is:

[Link](https://www.mssqltips.com/)

In the above code, the markdown file will have blue text with the word Link, which would send you to MSSQLTips when you click on it.

Explaining a How-To with GitHub Gists

We can also document why we're doing what we're doing in our gists as well. Like posting to a blog, gists allow you to document how you want, even featuring ways to bold, italicize, etc. your text. For an example, the text I wrote below the T-SQL and PowerShell code blocks:

I can **bold** or *italicize* text below code blocks, explaining what I need.  In addition, I can select the option to `Soft wrap` which makes it easier to type out information in a gist (otherwise, the scroll bar will keep moving right).  Note how `Soft wrap` outputs in a one-line code format on a gist.  Likewise, below I quote someone famous, showing how to quote someone.

> If you see it darling, then it's there.

How that appears on a markdown gist:

Summary

You can do many other things inside of markdown gists, and gists can also be used to create and save files of other extensions, like .sql or .ps1. Since we all tend to have our own way of solving problems, this offers a free way for you to build your own documentation, showing yourself how you step through the problem so you can return to it when you need, or re-use it for building a similar process or tool. Finally, as many of my colleagues agree with me on, finding a documentation tool that is compatible with development in general - due to characters and the difficulty of copying and pasting - can be quite the challenge and gists excel in this area.

Next Steps

• If you're already on GitHub, you click the link "Gists" on the middle of the top bar, and you'll automatically have the ability to create gists. You can also create markdown files on GitHub (readmes on GitHub are markdown files). GitHub is free, so you can sign up for free, if you're not on GitHub.
• When creating a gist, you will either Create secret gist or Create public gist, the former allowing you to keep your code private, provided that your link isn't shared.

About the author

Tim Smith works as a DBA and developer and also teaches Automating ETL on Udemy.

This author pledges the content of this article is based on professional experience and not AI generated.

View all my tips