MSP Business
MSPs, Document Your Scripts for Good
Automation tools have changed the managed service provider landscape forever. These tools have made it possible for network administrators to do what they never thought possible previously. This includes pushing out settings changes and sending updates to hundreds or thousands of users at once. The time saved thanks to these tools is truly priceless. Furthermore, automation tools also make unattended changes flow seamlessly. This makes it easier to make changes when most appropriate for the end user.
The best way for network administrators to take full advantage of automation tools is with scripts. These scripts can be written to perform multiple actions at once. Moreover, they can be scheduled to run at times that best serve the business. MSP scripts can be scheduled to run on a daily, weekly, monthly, or yearly basis. Best of all, they can be written with exactly that specific customer in mind, so that they meet the needs perfectly.
To learn all the baseline principles of creating MSP documentation you can refer to our guide.
For any MSP script to continue to be helpful after its first use, it must be properly documented. The annotations help to show what the script was intended for, and how it works. Notations explain the differences in revisions, and information about the author and editors. Scripts with proper comments throughout assist when troubleshooting issues, and help other technicians understand what the author’s intention with each line.
Here is a breakdown of the benefits and best practices in scripting documentation, as well as a few of the standard comments that should be added to every MSP script you write.
MSP Scripts Documentation Benefits
Automation scripts, as discussed, bring a myriad of different benefits to managed service providers and the people that they support. Properly documenting these MSP scripts maximizes these benefits, and makes these scripts effective for the long term. Here's a summary of how proper documentation helps to bring about these benefits.
Helps when troubleshooting issues
Your MSP scripts aren't always going to be perfect. Just because they work today, it doesn't mean they are going to work tomorrow. When issues do occur, you need to know where to look to address them. Adding good commentary throughout your script at the time of writing will help with troubleshooting future issues.
- The technical landscape is ever-changing - automation scripts must adapt. Operating systems are updated, and software versions change all of the time. Your MSP scripts must easily adapt to these changes. Be sure to document when the script was written, the software versions it was written for, and what software it’s expected to support.
- When scripts don't work, comments will help to understand why. Code that is properly commented throughout will have indicators as to what each line is doing, so that it’s easier to determine where to go next.
Further reading PowerShell Remote Alerts for Firewall
In this document you'll find a PowerShell script that checks the status of the services listed below and sends an email alert if any of them is turned off:
- Windows Firewall
- Windows Defender
- Windows Update Service
- Any installed third-party antivirus
Helps new technicians understand what is written
Here are a few of the benefits of using comments to make your code more digestible to future readers.
- Ideally, the scripts that are written are usable for an extended period of time. Writing, testing, and finalizing code can take quite a bit of time. Although the end goal of automation scripts is to save time in the future, the time spent at the beginning is definitely an investment. MSP scripts that are properly commented and easy to troubleshoot will be usable for a longer period of time, bringing a larger return on investment than would be the case with code that needs to be retired early.
- You want to be sure that you have an effective "hit by a bus" policy. Script writers come and go more often than you’d like in a competitive job market. As talented staff leave your managed service provider, you want the scripts that they’ve written to continue to be usable.
Developing a truly complete MSP scripts library can place a significant demand on resources. It’s important to make sure that the time and money invested in script development give an adequate return. Paying attention to proper documentation will ensure that your scripts outlive departing authors and are robust against the effects of passing time.
Further reading How Your Employees Can Contribute to Your MSP Business
MSP Scripts Documentation Best Practices
While any added commentary to scripts is better than nothing, properly written notations are the most effective. Header notations should be added to each script, as well as comments throughout. The combination of the two makes for the best notation standard.
Add header notes on every MSP script
The first thing that anyone should read when going through your script is the header. Your headers should contain important information, such as versions, author listings, and script purposes. This gives future editors a full understanding of what’s going on before they dive into the script too deeply.
- List important dates and version information.
- Include the author and editor notes.
A poorly written header will affect the lifetime and viability of an MSP script. It’s a shame to ruin the usefulness of good code with a poorly written header.
Comment throughout appropriately
Along with the header, you should have comments throughout your script as well. These comments can help you explain the intention of the most important lines of your MSP scripts. Furthermore, they can be used to describe the purpose of specific revisions. It is important to be concise and consistent in each of these annotations.
- Be concise. Keep it short, to the point and in keeping the flow of your script.
- Be consistent. Reviews of your script should be easy to understand. When troubleshooting, it's important to make it easy to scan through your MSP script as quickly as possible.
Every script should have an appropriate level of comment from beginning to end. Annotate as much as possible, but don't add too many. Chances are, you don't need a comment for every line of code. You need to find a way to comment enough, without adding too many annotations.
Checklist of Notations
It's a good idea to know what information should be documented for every script. These notations should be outlined in a standard of procedure (SOP) document for your MSP script writers. Regardless of whether or not there is an SOP, there are a few different key comment types to include. Here are five different types of annotations to consider for every script.
- Headers - As noted previously, every script that is written should include a header. The header should explain to the reader the intention of this script, and the author and version information. It should be obvious and stand out from the rest of the script.
- Warnings - If you feel that authors may edit your script in the future, adding comments warning them of potential slip-ups isn't a bad idea here. If you suspect that an edit might take place in the future that could cause issues, use the comments to add appropriate warnings to future editors.
- Bug Discovery - When bugs are found in MSP scripts, it's a good idea to use comments to indicate what was found, and how they were fixed. Your header can indicate revisions due to bugs, while in-code commentary can be used to show exactly what things went wrong, and where.
- Clarification - When scripts get confusing, it’s good practice to add comments to clear up any future confusion. Comments should be added to clarify intent for the areas where the author expects confusion, or by editors who have had to go back and troubleshoot faulty code.
- Variable definitions - Your MSP scripts are certain to contain variables relating to user input. Use comments to make it clear what each variable means, and possibly the constraints that apply to each variable. This way, any ineligible input will be avoided.
These types of comments are just a start. To further develop your script documentation, it’s a good idea to set up general standards of procedures for every script that your managed service provider authors. Additionally, templates for different comment sections, such as headers, can help to keep your MSP scripts uniform and simpler to support.
Conclusion
Automation scripts are powerful tools for managed service providers who write and use them appropriately. To ensure that the best use is made of these scripts, everything written should be properly annotated. Headers that give overviews of documents, and in-code notes that help to distinguish pitfalls and answer questions are the keys to success.
To best verify that all of your MSP scripts are documented properly, it’s a good idea to have someone, or a team of individuals, review each script that is authored. All scripts should have to be verified by these quality assurance testers before they are allowed to be used by your managed service provider’s technicians. Confirming proper documentation is a sure way to get the most out of your investment in these automation scripts.
In this document you’ll find a PowerShell script that checks the status of the services listed below and sends an email alert if any of them is turned off:
- Windows Firewall
- Windows Defender
- Windows Update Service
- Any installed third-party antivirus
