You probably heard (or read) a post I wrote back in July about how we built docs.microsoft.com/samples - I talked about some of the foundational elements and the process which we followed to build the site. Now that we’re a couple of months in, I thought I would take a step back and write about some of the lessons learned about shipping the new site, in the hopes that this will be helpful to others who will work on projects of similar scale!
I’ve been a big fan of GitHub Actions since last year’s Universe (read the post on building docs with them). As a matter of fact, I was such a fan that I moved my blog publishing process entirely to GitHub Actions and GitHub Pages. Recently, GitHub announced that the Actions engine is changing, which makes workflow management much easier - still in private beta, though. Recently I got an invite to try out the new functionality, though, so I thought I’d write up how I updated the blog publishing workflow to the new experience!
One of the biggest projects I’ve had the honor of being a part of has shipped a couple of days ago - docs.microsoft.com/samples. If you haven’t read the announcement blog post, I recommend you start there. Table of contents Inception Looking back First steps Improving the experience Published pages Automating releases Stack Conclusion Inception When we started working more in-depth on developer experiences, we realized that there are too many disjoint pages out there that provide an aggregation of code samples (and we ship thousands of samples that span hundreds of teams).
I love infrastructure and anything that has to do with it. That is - I love tinkering with different services and see what I can do to make them play nice with each other. I also like being efficient with what and how I deploy, and recently something dawned on my - I am spending way too much money on hosting my personal blog, that is 90% text. A recent analysis brought me to the number: 30$/mo.
For some time, at docs.microsoft.com, we’ve been using a non-standard way to document Java APIs. For example, if you take a look at this page, you will notice that it’s a regular API document. Behind the scenes, it was built with the help of Doxygen (generates structured docs from Java code), code2yaml (transforms Doxygen output into YAML) and DocFX (transforms YAML into static HTML). As we started documenting more APIs from across the company, we’ve encountered an interesting problem - Doxygen, while a versatile tool, relies on a set of conventions that are very much specific to its own stack and are less common in the Java developer community.
There comes a time when one needs to re-assess how and what they are using for their blog software. For years, I have been an avid WordPress user, jumping from shared hosting to shared hosting in search for a good deal, but always encountered issues - there was either little room to customize things, or I had to deal with the ever-growing bloat of a large code base for a little site.
I was just chatting with my good friend Anthony Chu about containers and an idea struck me - I love GitHub Actions, I love PowerShell. I wonder if the two would work together?
At GitHub Universe 2018, the team announced a new an exciting capability of the platform - GitHub Actions. At its core, this allows you to run "micro-CI" (or not so micro) within the repository itself. The benefit is two-fold: you can still plug in to other CI services, and you can also segment the workflow directly from the repository (there are some pretty interesting workflows out there already).
Yet another one of those times where people kept asking about something on Twitter, and I thought that it would be easier to write a blog post explaining the inner workings of things instead of responding in 280 characters. This time, this relates to "How can I build my own little docs.microsoft.com", so let's tackle the problem head-on.
In our team (docs.microsoft.com - we are hiring), we extensively use both GitHub and VSTS, for a variety of reasons. The problem of connecting the two came along as we were thinking about our public feedback channel. We ultimately want to have all user suggestions directed to the PM and engineering teams; however, internally all processes revolve around VSTS and engineering work is tracked there. The idea was to build a bot that can create VSTS work items from suggestions in GitHub.
We are all about GitHub on the docs.microsoft.com team. We host documentation there and just recently we launched content feedback that's storing comments in GitHub issues as well. Today, we moved all site feedback to GitHub as well.
We recently got a Nest cam, and we absolutely love the capabilities it brings to our home. One of the staples of the camera was the capability to record footage and then replay it later. The problem with that is we needed to pay for a subscription, and in my humble opinion, it's a bit pricey.
I am a big fan of doing a lot of the monotonous automation work through Continuous Integration (CI). Specifically, I work a lot with defining workflows for documenting managed (.NET-based) API reference documentation. In the process, we leverage several tools, as you can read from one of my previous posts. The reality of software is, however, that it changes. New updates are pushed, new NuGet packages are released, and with that, there is a very high probability that the documentation changed as well.
This is one of those questions that gets asked every week or so - I want to build documentation for my package the same way docs.microsoft.com does, but on my own server/cluster. While today we do not provide the entire infrastructure as a single open-source entity (but you can certainly read up on what we do behind the scenes), I thought I would write a short guide on how you can document your own NuGet packages and then publish the documentation on GitHub pages.
As a Program Manager, part of my job is to write technical specification documents. Our team recently switched to using our very own system (yes, we use the docs.microsoft.com infrastructure internally too) to write technical specs – content is on GitHub and Markdown-based. As part of that came the question – how do we aggregate comments when people review them?
As part of the project that I am working on, I need to make sure that I allow the user to specify what GitHub repository they want to bind to their Visual Studio Team Services build definitions. As part of the project that I am working on, I need to make sure that I allow the user to specify what GitHub repository they want to bind to their Visual Studio Team Services build definitions. I am using the library for that, but no matter what I tried, the repository just did not show up.
One of the key parts of my job as a Program Manager on the docs.microsoft.com team is to assess community contributions across different documentation repositories and areas. That might appear to be a very complicated task, and as we go, I will document more on the process. This post, however, is dedicated to setting up the core environment to make the task somewhat easy.
As we released the Visual F# documentation as open-source, one thing stood out as a challenge that needed to be tackled – content validation. There could be several things we could do, such as integrating extra validation rules in the build system or building a GitHub bot. I thought that as a learning experience, I will go the bot route. This post explains how I worked this problem.