Tag Archives: Community

Improving Documentation via the Community.

Have you ever had to deal with incorrect documentation? Or been frustrated by a typo? Or been annoyed that a how-to guide uses an old version of an interface?

Now you can fix it!

Many software providers are now using community-editable documentation online. This isn’t a Wikipedia style free-for-all, but a carefully moderated process ensuring that the resulting document is accurate.  If you come across an error in an online doc, or even a PowerShell help page, check and see if you can submit edits.

Continuous deployment pipelines mean that these edits can make it into live documentation in a matter of hours or days- impressive times if you’ve ever submitted an errata to a printed book, or submitted a bug request to get online documentation fixed.

docs.Microsoft.com

If you visit a Microsoft docs page, you’ll see an Edit link at the top of the screen (see (1) in the screenshot below). Clicking on this takes you to a page on Github with the source of the document. Click there to edit the file and a git fork will be made under your own profile- make your edits and submit a merge request and, once approved, your updates will appear in the original website. You’ll even get a little credit (see (2) in the screenshot below) for your contribution.

image

In this particular example I was following the step-by-step guide and noticed that the wording in the document no longer matched the Azure Portal. I was quickly able to suggest a fix and later that day the page was updated and anyone else following the instructions wouldn’t be misled. Two minutes of my time hopefully saved ten minutes of head-scratching by someone else.

VMware PowerCLI Example Scripts

As the name suggests, the source code for some example PowerCLI scripts has been published by VMware supported by members of the #vCommunity. If you find an error in the scripts you can pop over to Github and correct them- and remember this isn’t just the code of the script, but also it’s accompanying documentation.

image

In this example a typo in the get-help file was spotted and quickly corrected. Whilst the spelling mistake wasn’t a show-stopper this shows how quick and easy it is to contribute to these projects without being a coding guru.

Summary

Many of these projects use Github and learning how to use that version control platform isn’t arduous- especially for small changes like these- and is a useful skill to pickup if you don’t already have it. The important message here is you don’t need to be a developer to contribute to the code.

So, next time you spot a mistake in documentation, see if you can fix it yourself and help the next person who comes along.

VMware vExpert 2017

#vExpert 2017 Award

I’m honored to again be a member of VMware’s vExpert program following the 2017 award announcement yesterday evening.

[vExperts are] people who were particularly engaged with their community and who had developed a substantial personal platform of influence in those communities.

This idea of technical community is core to the award, and something that I believe VMware foster extremely well. The (separate but related) VMUG organisation is obviously a large part of this- I’m a regular at the London events – and between that and VMworld there’s the opportunity to meet fellow professionals in person. The vExpert Slack Channel is always busy but the wider VMware online community extends from Cloud Credibility, VMTN, VMware {code} and out into all the independent forums and blogs. Not forgetting Twitter of course.

So, much more to come from me through the next year and I look forward to continuing to be an active member of the vCommunity.