Regular IT guy

Just a guy – talking about technology … in an uncomplicated way.

Menu
  • Contact
  • Speaking
Menu

Azure VM Compute Documentation project

Posted on March 24, 2016 by Rick
Share on Social Media
twitter facebook linkedin email

I’ve been in my new role now for just under 3 months now and today I can actually SHOW you a little bit about what I have been working on.  I’ve been the point person in Azure Compute Engineering on a large refactoring project of our Azure Compute documentation.  I’ve been collaborating with our awesome Documentation team to make the Azure Compute documentation better.

How?

  • We’ve split the massive Azure Compute documentation set into two audience focused nodes
  • We are making our docs more tailored to specific audiences (Windows folks / Linux folks)
  • We are updating existing documents
  • We’re soliciting feedback on the refactoring and approach as well as identifying gaps that need to be addressed

It’s a big team effort and cross team focus. What’s involved? Well – for starters (as a Windows geek) I had to re-aquatint myself with Linux by immersing myself in Ubuntu and AzureCLI.  This has been my working environment (as a linux VM in Hyper-V client) for the last couple of months.

My Desktop Work Environment (As a Hyper-V Client VM)

I then had to start using git (locally and up in a private repo) for source control of markdown files (the format in which we write documentation) created in VS Code (so I can be cross platform on Linux and Windows) all while corralling various Program Manager resources across multiple groups to update and author net new docs.  If that wasn’t enough – we’ve done a MAJOR refactoring of the compute documentation by segmenting the “audience” into Windows admins and Linux SysAdmins.

NewToCSplit

That’s no small feat cracking apart the ToC, renaming hundreds of files and scanning / fixing thousands of links across this massive documentation repo.  It also involves rebuilding the Table of Contents into a more manageable configuration as well as consistency for links and referrals to other docs – not to mention all the OTHER docs that link to this set.  Luckily I was NOT part of that major chunk of work – I’ll leave that to the documentation experts. It’s LIVE NOW and propagating across the web. There are still errors in the doc links and misc issues that we are tracking down, but at least this is PUBLIC now.

Here’s one of my docs kicking off the Linux Virtual Machines for VM Compute – note the ToC on the left.

LinuxDoc

The part I find most interesting in this project has been revisiting the documentation approach and tailoring the documents to each audience so they get what they need, show them how to do it, point them to additional references and get them on their way.  What does that mean? At a surface level – you won’t see PowerShell references in the Linux section, or AzureCLI / Linux refs in the Windows section.  Once a doc is found, if someone chooses to browse the ToC for additional info, it’s more logical and easier to find complementary articles once they “pop in” from a search engine.  Lastly –we’re ensuring we touch each doc and update instructions with the latest way of managing the resource (Azure Resource Manager instead of “classic Service Manager” methods).  Don’t worry – we still recognize folks have a lot of Service Manager (Classic) VMs out there and need to continue to manage them – we’re making those docs easier to find too.

Lastly – I wanted to reference the “style” of voice and audience these docs are targeted towards.  This is still a work in progress. You will notice a difference comparing a “Linux doc” to a “Windows doc”.  Here’s an example “Create a Linux VM from AzureCLI for Dev and Test” document.  Notice the “get in and explain what’s up”, then some prerequisites, a summary of the commands in use and finally a “do it” section. Gone are the big verbose areas talking about stuff that was already covered elsewhere or too much background information.

LinuxExampleDoc

Finally – the best part….

Now that this is in place:

  • We’re quickly iterating on these documents to fix bugs and update the freshness
  • Ensuring they are acturate and up to date
  • Identifying GAPS that exist with the documentation so we can create NET NEW docs that are missing

Each of our docs are tied to their GitHub markdown files.  See a mistake or want to improve a document? just hit that “edit in github” link at the top to contribute to the existing document.

LinuxDoc

then edit directly on the web via GitHub.

LinuxDocEdit

A group of moderators will take your input and push it through where it makes sense or comment / reject the merge where it doesn’t make sense.

So what do YOU think? Have a look through the document set for Linux and Windows. As I mentioned, we are still fixin’ up some bugs and bad links (expected with the size and scope of change) – bare with us as we continue to do this. Shoot me a comment below or send me an email (rick.claus@microsoft.com) about the new concept or discuss missing docs you would like to see.

Share on Social Media
twitter facebook linkedin email

Follow me on Social Media
twitter facebook youtube linkedin

Recent Posts

  • Moved over to Dreamhost
  • Microsoft Azure HPC goodness
  • Whats new in Azure VM Images
  • Whats New in Azure Managed Disks
  • What up with Azure File Sync

Recent Comments

  1. Farhan Sattar on New Year, New Responsibilities
  2. Frederi on Tuesdays with Corey: Seasons Greetings and Until Next Year!
  3. Leon Han on HowTo: Bootable USB Stick for OS Install
  4. Frederi on Tuesdays with Corey: Seasons Greetings and Until Next Year!
  5. Rick Claus [rclaus@MSFT] on Tuesdays with Corey: Seasons Greetings and Until Next Year!

Archives

  • January 2023
  • March 2019
  • November 2018
  • October 2018
  • September 2018
  • August 2018
  • June 2018
  • May 2018
  • April 2018
  • March 2018
  • February 2018
  • January 2018
  • December 2017
  • November 2017
  • September 2017
  • August 2017
  • July 2017
  • June 2017
  • May 2017
  • April 2017
  • March 2017
  • February 2017
  • January 2017
  • December 2016
  • November 2016
  • October 2016
  • September 2016
  • August 2016
  • July 2016
  • June 2016
  • May 2016
  • April 2016
  • March 2016
  • February 2016
  • January 2016
  • December 2015
  • November 2015
  • October 2015
  • September 2015
  • August 2015
  • July 2015
  • June 2015
  • May 2015
  • April 2015
  • March 2015
  • February 2015
  • January 2015
  • December 2014
  • November 2014
  • October 2014
  • September 2014
  • August 2014
  • March 2014
  • February 2014
  • December 2013
  • October 2013
  • August 2013
  • July 2013
  • March 2013
  • February 2013
  • December 2012
  • November 2012
  • September 2012
  • August 2012
  • June 2012
  • May 2012
  • April 2012
  • March 2012
  • January 2012
  • December 2011
  • November 2011
  • October 2011
  • September 2011
  • August 2011
  • June 2011
  • May 2011

Categories

  • Azure
  • Azure 4 ServerHuggers
  • Azure IT Pro News Roundup
  • CH9 Videos
  • CloudOpsAdvocacy
  • Comments
  • Community
  • Debunking Azure Myths
  • Events
  • Helpful Tech
  • How To
  • interviews
  • Microsoft
  • Networking
  • PatchAndSwitch
  • Personal
  • Presentations
  • Security
  • Server
  • TechEd
  • Troubleshooting
  • Tuesdays with Corey
  • Uncategorized
  • Windows 8
  • Windows Server 8
  • Workarounds

©2023 Regular IT guy