How to Contribute to PowerShell Documentation

Let’s Meet Up In Florida!

Hi, folks. The Scripting Guy is hosting a PowerShell Saturday event in Florida on March 19, 2016. I’ll be speaking there with a bunch of PowerShell friends. Come join us for a great day of PowerShell learning. Find more information here.

How to Contribute to PowerShell Documentation

How many times have you found PowerShell documentation that was not up-to-date? Or maybe you could not even find the documentation you needed. Here is your chance to fill the gap.

PowerShell Community

One of the things I have enjoyed over these years doing PowerShell is the community. By community I mean the people I meet online and offline: Twitter , Facebook , LinkedIn , blogs, forums , user groups , events , and conferences. The PowerShell team at Microsoft has intentionally engaged the community in a way that sets a high bar for the other teams at Microsoft. The value of community has been proven out over the last few releases of Windows Management Framework (WMF). Feedback from the community has guided the features and fixes the whole way.

Community Documentation

As announced last year the documentation and release notes for PowerShell are now open source on GitHub. This means you, the community, can personally contribute and correct PowerShell documentation. You will even get proper credit for your contributions by seeing your name listed in the articles your have written or updated.

Career Booster

Many people do not like attention for themselves. The thought of your name in lights could be annoying. Most of us just want to see the community get accurate documentation. That is noble. But think about this:

When a potential employer sees your picture and name beside articles on a Microsoft web property, does that hurt or help your prospects?

I think it helps your career, and it gives you a sense of satisfaction at the end of the day. “I did that!”

Behind the Scenes

The PowerShell documentation you find on MSDN begins its journey over at GitHub. What is GitHub? GitHub is probably the largest open source collaboration platform in the world. Trust me, you want to learn this. It is what all the cool kids are doing these days. I’m still learning.

This chart summarizes the documentation parts:

The documentation	you see here	is maintained here.
PowerShell	TechNet Docs	n/a
WMF 5.0 Release Notes	MSDN Docs	GitHub Source
PowerShell DSC	MSDN Docs	GitHub Source

This chart summarizes the code parts:

The code	you see here	is maintained here.
TechNet Script Gallery	TechNet Gallery	n/a
PowerShell Gallery	powershellgallery.com	*GitHub Source
PackageManagement	WMF 3.0/4.0/5.0	GitHub Source

*To be clear, the community can contribute directly to PowerShell Gallery, but the Microsoft open source contributions are shared publicly on GitHub.

When you compare these two charts do you notice a pattern? The TechNet stuff is moving to the other platform over time. I am not making any announcements here, and I don’t have too much insider information. But judging from this public knowledge that seems to be the pattern going forward.

How to Contribute to Documentation

The PowerShell team has created a contribution guide explaining the process for contributing to documentation. Here is the general flow:

• Get a GitHub account.
• Read the brief contribution guide.
• Complete the Contribution License Agreement (CLA) legal thing.
• Identify where you want to contribute or revise.
  • Check current issues for others working on it.
    • If no one else, then open an issue and start.
    • If others have logged it, then contribute to their effort.
• GitHub fork.
• Compose your content.
  • Visual Studio Code is my editor of choice.
  • Use Markdown syntax.
• GitHub pull request.

At first this may seem like a lot of effort. However, once you get past the first time setup steps, it is fairly easy.

For today’s article I want to focus on how to write the content with Visual Studio Code and then how to do your first GitHub fork/pull.

Writing Markdown Content with Visual Studio Code

I am going to date myself with this next statement. I remember word processing in the 1990’s on Word Perfect for DOS. You had a view called reveal codes that showed the text formatting elements. This is a lot like that, or HTML, or any other markup language.

Let’s look at what you need to know to write PowerShell documentation. It’s really not that hard, but it might take some practice.

Setting Up Visual Studio Code

Here’s a walk-through to get started:

1. Download Visual Studio Code for free. Install it. Optionally, follow Code on Twitter.
2. Launch VS Code, and create a new file in the folder of your choosing. Save it with the .md extension.
3. Click the Split Editor and Open Preview buttons highlighted in the screenshot below. Now you can see your source and preview side-by-side.
4. Now start typing your content. Put line breaks after each sentence. This way it is easier to track changes later on GitHub.

Markdown

PowerShell documentation is written in Markdown. It is easier than HTML, but not quite as powerful either. You will find that markdown is very light-weight, user-friendly and fast. There are several flavors of Markdown, and we will use the GitHub flavor cited in the contribution guide. In addition to the GitHub markdown reference, there are many popular sites online with tutorials.

Here are screenshots highlighting some popular formatting options when writing PowerShell docs. This example comes from the credential documentation I wrote last month. The GitHub source is here.

Here is a summary of the formatting used in these screenshots:

• Two carriage returns make a new paragraph.
• Greater than indents a block quote.
• Asterisk at the beginning of a line makes a bullet.
• Single asterisk surrounding text is italics.
• Double asterisk surrounding text is bold.
• Single backticks surrounding text is for code elements.
• Triple backticks before and after a block of lines turns it into code. Well-known code formatting is applied by naming it after the first set of backticks.
• For links, surround the link text with square brackets and surround the link URL with round parentheses.

See the links above for more formatting options. Remember that .md files are just plain text with a few extra characters for formatting. It is actually quite easy and fun!

Publishing Your Documentation

NEWB ALERT: I am not a trained GitHub professional. The following guidance is my own inefficient process. Please be kind to us OPS folks learning DEV stuff. I know you can do this better than me, so help me out in the comments below.

So now I have a text file that needs to get to GitHub. There are a number of ways to do this. GitHub pros will use any one of many command line (or GUI) tools. I’m not there yet. I cheat and use the web interface.

If you are updating an existing article, then you can simply copy and paste your changes from Visual Studio Code into the GitHub web interface where you have chosen to edit the documentation. Here are the steps:

• Browse to the GitHub file containing the documentation you want to edit.
• On the top-right side of the article click the pencil to edit the file in your fork of the project.
  • This makes a copy of the file in your own GitHub account. This is called a fork.
• Now you can edit the text in the web interface. This is where you want to copy/paste to/from Visual Studio Code and edit the markdown.
• Once you have completed your edits, you can create a pull requestat the bottom.
  • A pull request tells the owner of the original file that you want them to pull your changes into their copy for publishing.
  • When you submit the pull request, give it a title and description for the change you are making. This helps the owner of the file understand what you are changing and why.
• Click the button to submit the pull request. Your change is give a number, and you will see a summary of your edits.
• Once the owner approves your edits, you will get a notification in your GitHub account. If they have questions or do not approve, then they will probably make notes on the request and ask for clarification or other edits.

Also worth noting is that the GitHub pros have already synced a local copy of the files from GitHub to their local machine, and that is what they open directly in Visual Studio Code. In that case, you can edit the file directly and post your changes with a pull request using local GitHub tools instead of the web interface. I aspire to do this.

If you are submitting an entirely new file, you can create that in your own GitHub account. Then submit a pull request to the master branch of the documentation.

To learn more about GitHub see this intro video from my buddy PSCookieMonster, Warren Frame.

Just do it.

The Scripting Guy is famous for closing his PowerShell articles by saying “and that’s all there is to doing x with PowerShell! ” I am not so bold in this case. There is an art to using GitHub, and I am still an apprentice. Now you know what I know. I hope this helps you on your journey to making an impact in the PowerShell community.

You have no excuses left now. Give it a try. Boost both your career and the community. Thanks in advance!