Next steps for the official PowerShell documentation
Summary: Learn about changes that we’ve already made for PowerShell content and what’s planned for the near future.
Hello scripters!
My name is Don Gill, and I am the new documentation manager for Windows PowerShell. With the 2016 PowerShell and DevOps Summit quickly approaching, I thought it would be a fantastic opportunity to introduce myself to the PowerShell community and share some changes that we are putting in place to help you stay more connected with the PowerShell development team, share your feedback and suggestions, and even contribute directly to improving the PowerShell documentation.
While I am new to PowerShell, I’ve been with Microsoft for nearly 17 years. In that time, I’ve had the pleasure of working in roles across developer support, technical evangelism, and community outreach before ultimately finding my passion — technical content development.
When I recently saw the opportunity to join the PowerShell content team, I jumped at the chance because I could clearly see that the space has two of the three elements that are critical to deliver amazing documentation experiences:
- A dedicated community of users learning and freely sharing best practices
- A great development team with a strong technical vision
- A non-proprietary authoring platform that enables everyone to contribute to an ever improving set of guidance
Any guesses on the missing critical element?
Windows PowerShell Documentation is moving to open publishing
Last November, the PowerShell content team ran a small pilot to publicly share the PowerShell Desired State Configuration (DSC) content source in the open MarkDown format though GitHub. The question we had was simple — given the opportunity, would the PowerShell community engage and directly contribute to improving technical content? I’m pleased to announce that the results have proven better than expected.
Since going live in early November, there have been nearly 600 commits and more than 200 pull requests from 34 different contributors in our GitHub repository for DSC and WMF 5.0. Contributions ranged from the submission of entirely new topics from the likes of PFE Ashley McGlone, to critical technical refinements from customers like Daniel Scott-Raynsford and Aleksandar Nikolić, and a plethora of legit fixes to code examples and typos from many, many others. Issues raised by customers like Jason Morgan, Jeremy Murrah, and Arie Heinrich have driven lots of internal discussion within our team and ultimately put us on the path to making smarter decisions on how to approach complex concepts in a simpler more effective way.
While it will take time to completely shift over to this model, I intend to open the entirety of the Windows PowerShell content to the community through open publishing on GitHub. If you want to help make a lasting contribution to the PowerShell community, PowerShell documentation is a great place to start.
What you can contribute to now
If you’re ready to kick the tires, contribution to PowerShell content is easy.
In the upper-right corner of every DSC topic, there is a Contribute link. When you select it, you go to our GitHub repository and the underlying source Markdown file of the content. Within GitHub, you can propose additions and updates to the content itself as well as changes and improvements to associated code and script examples directly in the content source file. After the proposed changes are accepted by my team, they are rolled together and republished on a daily basis. As a contributor, you are given full authoring contribution credit on every topic you help improve.
If you’re not already familiar with GitHub or the Markdown format or would like more detailed instructions about how to contribute, I’d encourage you to take a look at the contribution guidelines as a primer.
In the coming weeks and months, we’ll be shifting more and more of our Windows PowerShell content to this open publishing system and will be announcing its availability through the @PowerShell_Team Twitter account. Next up on the list for open publishing is the conceptual content within “Scripting with Windows PowerShell”. Stay tuned!
Lastly, if you are planning to attend the PowerShell and DevOps Summit, feel free to look me up and say, ‘Hi’. I’ve dusted off my old twitter account (@dongill) just for the occasion. I’d love to meet you and hear your perspectives on how we can improve the overall help and documentation experience for Windows PowerShell.
Don Gill
Windows PowerShell
Light
Dark
0 comments