Authoring our guidance in the open … valuable? … will you engage with authors?

In June 2015 we entered the world of open source solutions, when we published the Folder-Management-Extension. Core objectives for the move were to be transparent, share samples, and encourage the community to contribute. Two years later, we created the Guidance staging repository, giving you an early glimpse into upcoming guidance and more importantly, an opportunity to influence the guidance before it’s published.

What’s our current authoring process?

Our guidance authoring process is fairly simple. Here’s a high-level view to give you an insight and our authors a checklist.

You have two opportunities to influence and contribute to our guidance!

Collaborate with product owner (PO) to define an article outline in, documented in a traceable work item (WI).

First DRAFT of the article is authored in Word. We collaborate with PO using comments and revision tracking.

When we have a first DRAFT, convert the Word document to markdown.--------------- from here we work in open source

We create a feature/topic branch and submits pull requests for each DRAFT. Engage with all Rangers and community to validate the content.--------------- from here we continue to work in open source and internal publication repo

When we have a final DRAFT, create a feature/topic branch on the VS.Articles git repo and submit a pull request (PR).

PM works with the content editors to validate style, tone, content, and polish the content.

When editor(s) accept the PR, the continuous integration pipeline builds and publishes the article to aka.ms/techarticles.

When users (you) comment on the pull requests or raise an issue, we collaborate with our PO to prioritise the revisions.

Deploy an application efficiently to geo-graphically distributed sites on the cloud

Phase the rollout of an application through rings

Gate the rollout of an application using health monitoring tools

Run automated tests efficiently in a pipeline

Apply environment-specific configuration just before deployment

Manage secrets for production deployments

Integrate with a change management system for compliance

In the stories section we’re working on the “our journey of transforming to a devops culture” story. We share how we embarked on a cultural shift that allowed us to "rub DevOps" on our operational processes, and embrace self-organized, self-managed and autonomous teams.