Best Practice...Script Documentation

If you are like me you hate writing documentation.  Have you heard yourself say, "I know how the process/script/equipment works.  Why do I have write it down?"  Well, the reality is that you may not be managing the said process/script/equipment forever.  Documentation is the right thing to do.  It makes it easier for others to follow the flow of a script, it can give examples of how to run the script, and it allows the coder to keep track of changes made over the course of the scripts lifetime.

Powershell is easy to script and you can use the following template get started:

<#

.SYNOPSIS
This is a brief description of what the script/function does

.DESCRIPTION
This is a more detailed explanation of the script/function

.PARAMETER name
An explanation of a specific parameter (if used).  Replace 'name' with the parameter name

.EXAMPLE
This shows examples of how to run the script/function.  You can have multiple .EXAMPLE sections if you like to show more than one example

.NOTES
This section is for any miscellaneous information regarding the script/function

.LINK
This section would contain a URL (beginning with either HTTP:// or HTTPS://) that can be a cross-reference to other help sites.  You can have multiple .LINK sections
#>

I also like to add a VERSION HISTORY section to the script.  That way I can keep track of changes that have been made to the script.  To add version history you use the following within the <# #>:
   # VERSION HISTORY
   # 
   # Version 1.2 (January 1, 2017)
   # Changed the GET-ADUser statement to include both domains

You will see that some of the scripts I have put on this blog do not follow this standard.  That is because some of these scripts are not in Production.  If I create a script that will be used by people other than myself, I will use my template.

I hope you find this helpful.  Your boss and colleagues will appreciate the effort.