|
| 1 | +--- |
| 2 | +title: "How to Write for PowerShell.org" |
| 3 | +description: "Two ways to submit an article to PowerShell.org, best practices that get you published faster, and why claiming an author page is worth five minutes of your time." |
| 4 | +author: Gilbert Sanchez |
| 5 | +authors: |
| 6 | + - Gilbert Sanchez |
| 7 | +date: "2026-06-23T00:00:00+00:00" |
| 8 | +categories: |
| 9 | + - Tutorials |
| 10 | +tags: |
| 11 | + - contributing |
| 12 | + - community |
| 13 | + - writing |
| 14 | +--- |
| 15 | + |
| 16 | +There's a thought that stops a lot of good articles: *who am I to write for |
| 17 | +PowerShell.org?* |
| 18 | + |
| 19 | +It's our brains safety net from the (highly unlikely) possibility of getting |
| 20 | +denied. Or worse! Accepted! And now we're forever on the hook to be an expert. |
| 21 | +But it's not true. |
| 22 | + |
| 23 | +You don't need to be an **MVP**. You don't need a **blog**, a **following**, or |
| 24 | +a **clever opinion** about the pipeline. You need one thing you figured out that |
| 25 | +the documentation didn't explain well. The `-Filter` quirk that cost you and |
| 26 | +afternoon. The script that finally tamed a chore you'd been doing by hand for a |
| 27 | +year. If it helped you, it'll help someone else who's about to lose the same |
| 28 | +afternoon. |
| 29 | + |
| 30 | +> [!IMPORTANT] |
| 31 | +> And here's the part that should lower your blood pressure: **nothing you submit |
| 32 | +> goes live unreviewed**. |
| 33 | +
|
| 34 | +A maintainer reads every submission, helps shape it, and |
| 35 | +edits for clarity and formatting before it publishes. You are not flipping a |
| 36 | +switch that broadcasts your rough draft to the world. You're starting a |
| 37 | +conversation with people who want you to succeed. |
| 38 | + |
| 39 | +So let's get you published. There are two ways in, so pick the one that matches |
| 40 | +how comfortable you are with Git because both land in the same place. |
| 41 | + |
| 42 | +## Path A: The GitHub issue (no Git required) |
| 43 | + |
| 44 | +If "fork the repo" already made you tense up, this path is for you. You'll never |
| 45 | +touch a command line. |
| 46 | + |
| 47 | +Open the [guest blog post |
| 48 | +form](https://github.com/PowerShellOrg/PowerShellOrgWebsite/issues/new?template=guest-blog-post.yml) |
| 49 | +and fill it out. The form does the structuring for you. It asks for exactly what |
| 50 | +we need and nothing else: |
| 51 | + |
| 52 | +- **Article title** and **your name** as you'd like it displayed. |
| 53 | +- **Submission type**, and this is the part people miss: you can choose *"Pitch |
| 54 | + -- I'd like feedback before writing."* You don't have to show up with a |
| 55 | + finished draft. Float the idea first, and a maintainer will tell you if it's a |
| 56 | + fit and help you shape the angle before you spend the writing time. |
| 57 | +- **Description**, one or two sentences. This becomes your SEO blurb and social |
| 58 | + card, so it earns its keep. |
| 59 | +- **Category** and **tags** (more on choosing these well below). |
| 60 | +- **Article content**, where you paste your full Markdown if you have a draft. |
| 61 | + Leave it blank if you're pitching. |
| 62 | + |
| 63 | +Submit it, and the rest happens in the issue thread. That's the whole path. No |
| 64 | +branches, no merge conflicts, no Git vocabulary. |
| 65 | + |
| 66 | +## Path B: The pull request (for the Git-comfortable) |
| 67 | + |
| 68 | +If you already live in Git, you can submit the article directly and watch it |
| 69 | +flow through the same review. |
| 70 | + |
| 71 | +1. Fork the repo and create a branch for your article. |
| 72 | +2. Add a Markdown file in `content/articles/` using the date-slug naming |
| 73 | + convention: |
| 74 | + |
| 75 | + ``` |
| 76 | + content/articles/YYYY-MM-DD-your-article-slug.md |
| 77 | + ``` |
| 78 | + |
| 79 | +3. Start it with this front matter: |
| 80 | + |
| 81 | + ``` |
| 82 | + --- |
| 83 | + title: "Your Article Title" |
| 84 | + description: "A 1-2 sentence summary used for SEO, social cards, and the article list." |
| 85 | + author: Your Name |
| 86 | + authors: |
| 87 | + - Your Name |
| 88 | + date: "YYYY-MM-DDT00:00:00+00:00" |
| 89 | + categories: |
| 90 | + - Category Name |
| 91 | + tags: |
| 92 | + - tag1 |
| 93 | + - tag2 |
| 94 | + --- |
| 95 | +
|
| 96 | + Your article in Markdown goes here. |
| 97 | + ``` |
| 98 | + |
| 99 | +4. Open a pull request with a short description, and we'll review it there. |
| 100 | + |
| 101 | +> [!TIP] |
| 102 | +> Let VS Code do the boring part. Install the [Front Matter |
| 103 | +> CMS](https://frontmatter.codes/) extension, open the repo, and run **"Create |
| 104 | +> content"** in the `content/articles` folder. It scaffolds the |
| 105 | +> `YYYY-MM-DD-slug.md` filename and every front-matter field for you, and it |
| 106 | +> gives you a form for the title, description, category, and tags instead of a |
| 107 | +> wall of YAML you can typo. It turns the single most error-prone step into a |
| 108 | +> fill-in-the-blanks. If you only adopt one tool from this article, make it this |
| 109 | +> one. |
| 110 | +
|
| 111 | +## Best practices that get you published faster |
| 112 | + |
| 113 | +None of these are gates. They're the small things that mean a maintainer spends |
| 114 | +their time on your ideas instead of your formatting. |
| 115 | + |
| 116 | +- **Open by telling readers what they'll walk away with.** A two-sentence intro |
| 117 | + that promises a payoff beats a warm-up paragraph every time. |
| 118 | +- **Write in Markdown, and fence your code with a language hint.** Use ` |
| 119 | + ```powershell ` so your samples get syntax highlighting instead of a gray |
| 120 | + slab. |
| 121 | +- **Run your code before you paste it.** A snippet that works on the first try |
| 122 | + is the difference between a reader trusting you and a reader closing the tab. |
| 123 | +- **Keep the title concrete.** "Speed up your console with PSReadLine predictive |
| 124 | + IntelliSense" tells me what I'm getting. "PowerShell tips" tells me nothing. |
| 125 | + |
| 126 | +That's the bar. It's lower than the one in your head. |
| 127 | + |
| 128 | +## Categories and tags are how people find you |
| 129 | + |
| 130 | +It's tempting to treat these as paperwork and pick whatever's first in the list. |
| 131 | +Don't. They're the difference between an article that's read once and one that |
| 132 | +keeps getting found. |
| 133 | + |
| 134 | +Pick the single **category** that fits best. The current set: |
| 135 | + |
| 136 | +> Announcements - Books - DevOps - Events - Graph - In Case You Missed It - |
| 137 | +> News - PowerShell Summit - PowerShell for Admins - PowerShell for Developers - |
| 138 | +> Scripting Games - Tips and Tricks - Tools - Training - Tutorials |
| 139 | +
|
| 140 | +Category is the big bucket. It's how someone browsing "PowerShell for Admins" |
| 141 | +stumbles onto your piece months from now. **Tags** are the specific hooks: the |
| 142 | +cmdlets, modules, and concepts your article actually touches (`psreadline`, |
| 143 | +`regex`, `azure`, `pester`). Three to five honest, specific tags beat a dozen |
| 144 | +vague ones. Tag what's really in the article, not every PowerShell word you can |
| 145 | +think of, and your post surfaces next to its actual neighbors. |
| 146 | + |
| 147 | +## Claim your author page |
| 148 | + |
| 149 | +Once you're credited on an article, you can give yourself a real author page at |
| 150 | +`/authors/<your-name>/`: an avatar, a tagline, a short bio, and links back to |
| 151 | +your own site and socials. Every article you write points back to it. It's a |
| 152 | +small, durable corner of the PowerShell community that's *yours*, and it builds |
| 153 | +with each post. |
| 154 | + |
| 155 | +It's opt-in. Skip it and your byline still works exactly as before. But it takes |
| 156 | +about five minutes, so why leave it on the table? You can see an example of mine |
| 157 | +at the bottom. |
| 158 | + |
| 159 | +Your profile is a single file at `content/authors/<slug>/_index.md`. The one |
| 160 | +rule that trips people up: the `<slug>` has to match your byline exactly |
| 161 | +(lowercased, spaces to hyphens), or the page attaches to nothing. |
| 162 | + |
| 163 | +So let the helper script handle it: |
| 164 | + |
| 165 | +```powershell |
| 166 | +./tools/new-author.ps1 "Jane Doe" |
| 167 | +``` |
| 168 | + |
| 169 | +That scaffolds `content/authors/jane-doe/_index.md` with every field commented. |
| 170 | +Fill in what you want, delete the rest: |
| 171 | + |
| 172 | +```yaml |
| 173 | +--- |
| 174 | +title: "Jane Doe" # required -- keep this as your byline name |
| 175 | +preferred_name: "Jane" # optional -- changes only how your name displays |
| 176 | +tagline: "Cloud automation, mostly." |
| 177 | +gravatar_hash: "..." # MD5 of your lowercased email -- keeps your email private |
| 178 | +github: "https://github.com/janedoe" |
| 179 | +website: "https://janedoe.dev" |
| 180 | +# twitter / mastodon / linkedin / bluesky also supported |
| 181 | +--- |
| 182 | + |
| 183 | +Your bio in Markdown goes here. |
| 184 | +``` |
| 185 | + |
| 186 | +One thoughtful detail worth calling out: you can set an avatar **without** |
| 187 | +putting your email address in a public repo. Store the MD5 hash of your |
| 188 | +lowercased email as `gravatar_hash`, and Gravatar serves your picture while your |
| 189 | +email stays private: |
| 190 | + |
| 191 | +```powershell |
| 192 | +$email = "jane@example.com" |
| 193 | +[System.BitConverter]::ToString( |
| 194 | + [System.Security.Cryptography.MD5]::Create().ComputeHash( |
| 195 | + [System.Text.Encoding]::UTF8.GetBytes($email.Trim().ToLowerInvariant()) |
| 196 | + ) |
| 197 | +).Replace("-", "").ToLowerInvariant() |
| 198 | +``` |
| 199 | + |
| 200 | +And if your name ever changes, `./tools/new-author.ps1 "Old Name" -To "New Name"` |
| 201 | +rewrites your byline across every article and adds a redirect so your old |
| 202 | +profile URL keeps working. Open a PR with the result. |
| 203 | + |
| 204 | +## Your turn |
| 205 | + |
| 206 | +The whole point of PowerShell.org is that it's built by the people who use |
| 207 | +PowerShell, and that includes you. You don't have to be sure it's good enough. |
| 208 | +That's literally what the review is for. Pitch the idea, paste the draft, or |
| 209 | +send the PR, and you won't be doing it alone. There's a community on the other |
| 210 | +side of that submit button that wants to help you get it across the line. |
| 211 | + |
| 212 | +[Start here.](https://github.com/PowerShellOrg/PowerShellOrgWebsite/issues/new?template=guest-blog-post.yml) |
0 commit comments