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.
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.
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.
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.
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.
then edit directly on the web via GitHub.
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.
