Tips for PowerShell Gallery Success

I've been thinking a lot about the PowerShell Gallery lately. Microsoft can't provide everything you might want in PowerShell. Even if it could, it would make PowerShell gigabytes in size. The reality is that Microsoft will contribute the core engine and cmdlet set. But applications of the PowerShell management engine to solve specific tasks will be left to the PowerShell community. These solutions can be published in the PowerShell Gallery. I believe your PowerShell configuration workflow should be:

• Install latest version of PowerShell
• Update help
• Install the latest version of the PowerShellGet module
• Install additional modules from the PowerShell module that have been tested, approved, and meet your business needs.

But this article is directed to PowerShell module authors, those of you who put in many hours of work, often on your own time, to develop, test, and support a PowerShell-based solution. And after all of that effort, you kindly share your project with the community and publish it to the PowerShell Gallery. While it isn't required, it is nice to receive validation for our endeavors, and this includes watching the download count rise.

As part of my drive to raise awareness of content in the PowerShell Gallery, I've started hosting a series of reports including recently published modules. I've been looking through the reports and modules and realize there are steps you can take to increase the installation odds for your baby.

Module Description

In your module manifest, there is a section for a description. Use it. If I can't see a meaningful description, I will be less likely to adopt your code.

When I look at reports in the PSGalleryReport repository, the description is very helpful. In looking through other modules, I've realized the description can be more than a few words. Don't treat it as an abstract. Write a meaningful description. I recognize I need to update my module descriptions.

Public Repository

Barring proprietary code elements, your module should have a public repository. This repository should be included in the module's PrivateData section. I consider this a requirement, especially if the module author is not a corporate entity. If Pat PowerShell publishes a module to the PowerShell Gallery, and there is no public repository; I am very unlikely to install the module. Without a public repository, I have no way of gauging the quality of the code.

Complete README

I strongly encourage you to have a complete README file in your repository. This file is your primary "marketing" tool. An effective README will show me what the module does and how to use it. Files with little to no text are a red flag that I should move on. Either the module isn't ready for widespread use, or the author is doing the least amount of work. If that's the case, I'll have doubts about the quality of their code. A good README is a sign of a professional project and something I am likely to look at further. Based on a few recently published modules, take a look at https://github.com/chris-peterson/pwsh-gitlab and https://github.com/junecastillote/MS365HealthReport for effective README files. Good documentation is a sign of a mature module, and the README file is the first place to start.

Follow Naming Conventions

The ingredient in your recipe for success is to follow accepted naming conventions for PowerShell commands. If I look through your code, and I will, and see publicly exported module commands like these:

• GetUpTime
• Run-File-Cleanup
• Set_Start_Time
• Execute_remote_shutdown

I am unlikely to trust your work. The Verb-Noun naming convention is a widely adopted and well-accepted community standard. If you are publishing a module with these types of commands, it makes me question the quality of the rest of your work.

By the way, for those of you still learning to write PowerShell functions and modules, these would be the preferred names.

• Get-UpTime
• Invoke-FileCleanup
• Set-StartTime
• Start-RemoteShutdown

Summary

We need community members to publish high-quality modules to the PowerShell Gallery. I want to see you succeed and be recognized for your efforts. I believe that if you take these recommendations to heart, you will be well on your way.

And for all of us, we need to spread the word about modules we find invaluable. There is no marketing budget for the PowerShell Gallery. It is up to the community.

---

---