Posts in documentation

One Line Python Documentation

November 7, 2019

Whenever we talk about documentation infrastructure, one of the most common pieces of feedback I hear from developers is that it’s too complicated to set up. There is just too much configuration, fiddling around and trying to make sure that the output is produced in way that is expected. That’s why back in June I set out to build a documentation CLI that allows one to produce docs with one liners.

Building A Documentation CLI

June 8, 2019

When building documentation for your product, you will often encounter situations where you need to mix and match a bunch of content that comes from different sources. It becomes a bit more complex when you need to start dealing with different platforms, e.g. documenting APIs for Python, .NET and Java all in one place. We do all that and more on docs.microsoft.com, where we host documentation that is both hand-written and generated automatically from code - DocFX is a very powerful and versatile system that allows you to do that with the help of pre-defined contracts for structured and unstructured content.

Building Java API Docs With DocFX

February 24, 2019

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.

Building Docs With GitHub Actions

December 7, 2018

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).

On Structured Content

October 9, 2018

October marks my 3rd year of working on docs.microsoft.com - a lot has changed since we first started with the project, and I wanted to focus on one very specific aspect of our tooling and infrastructure for this essay. The topic is closely related to my personal mission: empower people to spend time in meaningful ways. At docs.microsoft.com, we push tens of thousands of lines of content daily in the API documentation space.

Easy Docs For Node And Python

September 15, 2018

Let’s say you are shipping a library. And let’s say that you are developing it in JavaScript, TypeScript or Python. As a developer, you probably want to have it documented. But documentation is complicated, right? You have to have a tool, integrate a bunch of plugins into it, and then have a process to somehow transform those into the proper formats. A lot of hassle. But what if it wouldn’t be?

DIY Docs In The Cloud

June 29, 2018

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.

5 Things Learned Generating API Documentation

June 21, 2018

API documentation - something that often remains an after-thought for developers purely because writing it can be cumbersome, it requires working with a bunch of different tools (often very old), and maintaining it makes developers cringe just because that means they have to come up with good examples and descriptions, and let's face it - most developers would rather focus on writing code.

Summer Of Docs - Documenting .NET Libraries

June 1, 2018

Summer is here, the city finally feels like you can take pictures of it from above without being “head in the clouds”, and that also means that it’s time to document how we generate .NET documentation on docs.microsoft.com. A while ago I wrote a post about documenting NuGet packages, and while it was a generally good description of high-level tools, it also missed the key detail - how to use DocFX to render the docs.

Visual Studio Code And docs.microsoft.com API Docs

November 25, 2017

Last week I thought I would sit down and learn how to write a Visual Studio Code extension - what better way is there to test the documentation your company ships and give yourself the best holiday present of the year? (photo by monicore) I will start this by saying right away how easy it is to work on the extension across two platforms - part of it was written on a Windows machine, and another part of a mac.

Building Docs For NuGet Packages With VSTS And GitHub Pages

May 27, 2017

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.

How We Build Documentation For .NET-Based SDKs

April 14, 2017

If you are following the news around our new technical documentation experience, you probably know that last week we revamped our managed reference experience and launched the .NET API Browser. In today’s post, I thought I would go into the nitty-gritty of the process and talk about how exactly we generate reference documentation for .NET Framework and related managed SDKs.

On Importance Of Documentation

October 30, 2016

This October marks a year since my switch from working on client software to working on the unified Microsoft documentation experience. Throughout the past year I had to learn a tremendous amount of absolutely new (to me, at least) things that totally changed my perception of what the importance of documentation is.