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

  • Article

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.

SNAGHTML9b52f27

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!

image

  1. Collaborate with product owner (PO) to define an article outline in, documented in a traceable work item (WI).
  2. First DRAFT of the article is authored in Word. We collaborate with PO using comments and revision tracking.
  3. When we have a first DRAFT, convert the Word document to markdown.
    --------------- from here we work in open source
  4. 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
  5. When we have a final DRAFT, create a feature/topic branch on the VS.Articles git repo and submit a pull request (PR).
  6. PM works with the content editors to validate style, tone, content, and polish the content.
  7. When editor(s) accept the PR, the continuous integration pipeline builds and publishes the article to aka.ms/techarticles.
  8. When users (you) comment on the pull requests or raise an issue, we collaborate with our PO to prioritise the revisions.

What’s planned?

Infinity Loop with gears representing DevOps in Practice

Here’s a list of DevOps articles we’re planning and working on in github.com/ALM-Rangers/Guidance:

  • Manage database upgrades
  • Build and deploy a collection of micro-services
  • Manage dependencies between applications
  • Build and deploy SharePoint applications
  • Deploy an application to a cluster
  • 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

image

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.

Feedback

1. What do you think of our new guidance style on https://aka.ms/techarticles?

2. What do you think about our authoring process?

3. How can we do better?

We need your feedback! Here are some ways to connect with us:

  • Add a comment below
  • Ping us on twitter image