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.
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.
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.
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).
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.
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.
Thought I’d start a series of videos talking about documentation and anything related to it.
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 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.
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? 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.
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.
This Friday I had the pleasure of being interviewed by Jason Young and Carl Schweitzer on MSDevShow, and boy did we talk about a bunch of stuff!
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.
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.