{"id":7875,"date":"2017-04-14T19:51:00","date_gmt":"2017-04-14T19:51:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/premier_developer\/?p=7875"},"modified":"2019-03-05T15:16:52","modified_gmt":"2019-03-05T22:16:52","slug":"documentation-in-a-devops-world","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/premier-developer\/documentation-in-a-devops-world\/","title":{"rendered":"Documentation in a DevOps World"},"content":{"rendered":"

In this post, Application Development Manager, Chris Mason<\/strong> discusses the challenge of keeping documentation up to date in this fast moving DevOps world.\u00a0 In addition, he spotlights DocFX and writes a build task extension which integrates it into your build pipeline.<\/p>\n

\n

Overview<\/h3>\n

We talk a lot about DevOps today and it represents a major strategy and focus for our developer platforms with Visual Studio Team Services (VSTS) and Team Foundation Server (TFS). There are plenty of examples out there covering various aspects of application deployments in a DevOps world: deploying apps, database migrations, and coded infrastructure. However, one area that seems to escape coverage is– documentation<\/em><\/strong>.<\/p>\n

If we are deploying apps on a \u201ccloud cadence\u201d then we can expect new features to be rolling out to users every few weeks. When a user sees a new button, a new option, or a new color code in an app, they are going to want to know what it does. This means we need a rapid cadence to build and deploy new documentation so that when any new feature rolls out to the user, they can go and quickly find supporting information for it.<\/p>\n

This idea is not earthshattering or new. Dynamic documentation generation has been around for ages, for example, the old Sandcastle<\/a> project. While great for generating API level documentation for developers to look at, it is not necessarily the most user friendly result when done.<\/p>\n

DocFx<\/h3>\n

Another option that is available today is the open-source option called DocFx<\/a> which is developed and maintained by the .NET team. DocFx is the underlying technology behind the newly redesigned docs.microsoft.com<\/a> which represents a clean, modern way we are presenting documentation on sites going forward. We have already migrated documentation for several products including Azure and .NET Core onto the new platform and more are actively in transition.<\/p>\n

DocFx is similar to other platforms like Jekyll<\/a> or ReadTheDocs<\/a> where you write the content in Markdown, provide some high level template structure to your site, run the tool of choice and out comes a site with fully rendered html, CSS, and required JavaScript. In addition to supporting Markdown files, DocFx can also process Swagger json files, as well as managed code objects.<\/p>\n

Introducing DocFx Build Task<\/h3>\n

DocFx gives us a lot of power to create great documentation for our product, but I wanted a way to be able to put that into a continuous integration \/ continuous delivery pipeline. My original approach to this problem was to create a build pipeline in VSTS that would download and install something like Chocolately, use Chocolately to grab the latest DocFx package, then run a command line build task that would invoke DocFx against our project. Unfortunately, that solution did not pan out as I had hoped and ended up being a bit messy overall.<\/p>\n

So, I wrote a VSTS build task extension<\/a>! My extension is called DocFx Build Tasks<\/a> and it aims provide an easy way to integrate DocFx into your build pipeline so you can generate content that can later be pushed out through a release pipeline. The agent is in a first release, so try it out, give me feedback and let me know if you feel anything that is missing.<\/p>\n

Example Walkthrough<\/h3>\n

We can now try this extension out and see what kind of workflow we might be able to get working. For my example project, I started with the DocFx seed project<\/a>. I created a new Git repository in VSTS and pushed this code base into there. No other changes were made to the seed project.<\/p>\n

Install the Extension<\/h4>\n

Open the extension from the VSTS Marketplace<\/a>. For VSTS click \u201cInstall\u201d for TFS click \u201cDownload\u201d<\/p>\n

\"\"<\/p>\n

Follow the instructions to complete the installation of the extension (in my case, I am using VSTS and that is how I will refer to it from now on).<\/p>\n

Configure Build<\/h4>\n

Navigate to the \u201cBuild\u201d hub within VSTS. Click \u201c+ New\u201d to create a new build.<\/p>\n

\"clip_image004\"<\/a><\/p>\n

You can select whichever template you would like as we are going to ultimately reconfigure it anyways.<\/p>\n

\"\"<\/p>\n

Assuming you pick \u201cVisual Studio\u201d, you end up with the following setup.<\/p>\n

\"\"<\/p>\n

Remove every existing task within the setup. Click \u201c+ Add Task\u201d and add the following two tasks:<\/p>\n

\u00b7 Create DocFx Documentation<\/p>\n

\u00b7 Copy and Publish Build Artifacts<\/p>\n

Your pipeline should look like the following:<\/p>\n

\"clip_image010\"<\/a><\/p>\n

For the Create DocFx Documentation step, in most cases, you only need to provide a path to the docfx.json file in your source control.<\/p>\n

\"clip_image012\"<\/a><\/p>\n

If you need to override how DocFx is invoked, you can specify those options as well. We are going to want to publish our generated content to a web site ultimately so we will need to configure the copy and publish build artifacts.<\/p>\n

\"clip_image014\"<\/a><\/p>\n

Save and queue the build and your site should be generated within a few minutes and published as an artifact from our build.<\/p>\n

Deploy to a Web App<\/h4>\n

In my example, I am using an Azure Web App to deploy my site\u2019s content to. I went to the Azure portal, created a new web app and then reset the credentials<\/a> to support ftp deployment.<\/p>\n

Back in VSTS, I navigate to the \u201cRelease\u201d hub and click the \u201c+\u201d to create a new release.<\/p>\n

\"\"<\/p>\n

I started with an Empty release definition for this example.<\/p>\n

\"\"<\/p>\n

Click \u201cNext,\u201d select the name of the build definition you created in the previous step, you can choose if you want it to implement continuous deployment or not, and I left mine as the \u201cHosted\u201d build queue. Click \u201cCreate.\u201d<\/p>\n

In your new release definition, setup your environments. This can follow whatever flow makes sense for your requirements but an example flow could be something like Draft -> QA -> Live. Select an environment and add a single task:<\/p>\n

\u00b7 FTP Upload<\/p>\n

For Authentication Method, I used FTP Service Endpoint. This allows me to create a generic service endpoint based on the reset FTP credentials of the site I setup. Once I create that service endpoint, I can reference that within the task. Select the source folder to the artifacts folder you previously built. The remote directory for an Azure web app would be \/site\/wwwroot.<\/p>\n

A couple notes, in the Advanced section, you want to make sure you enable \u201cOverwrite\u201d as well as \u201cPreserve file paths.\u201d Without the second option, everything would be copied to a flat file format which would cause the site to not render correctly. The full release task is shown below:<\/p>\n

\"\"<\/p>\n

Save and start a new release and in about a minute, you should have your newly generated CI\/CD DevOps friendly documentation site.<\/p>\n

\"\"<\/p>\n

We have seen in this example how we can now incorporate documentation writing as part of a DevOps mindset. Connecting written content to a continuous delivery pipeline provides an opportunity for end customers to ensure they are up to date on the latest and greatest details about your product. As far as the extension shown here is concerned, this is its first release and I would love to hear how it works for you or if there are any suggestions for improvement.<\/i><\/p>\n

\n

Premier Support for Developers<\/a><\/strong> provides strategic technology guidance, critical support coverage, and a range of essential services to help teams optimize development lifecycles and improve software quality.\u00a0 Contact your Application Development Manager (ADM) or email us<\/a> to learn more about what we can do for you.<\/p>\n","protected":false},"excerpt":{"rendered":"

In this post, Application Development Manager, Chris Mason discusses the challenge of keeping documentation up to date in this fast moving DevOps world.\u00a0 In addition, he spotlights DocFX and writes a build task extension which integrates it into your build pipeline. Overview We talk a lot about DevOps today and it represents a major strategy […]<\/p>\n","protected":false},"author":582,"featured_media":37840,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[35,22],"tags":[21,205,3],"class_list":["post-7875","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-alm","category-devops","tag-devops","tag-documentation","tag-team"],"acf":[],"blog_post_summary":"

In this post, Application Development Manager, Chris Mason discusses the challenge of keeping documentation up to date in this fast moving DevOps world.\u00a0 In addition, he spotlights DocFX and writes a build task extension which integrates it into your build pipeline. Overview We talk a lot about DevOps today and it represents a major strategy […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts\/7875","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/users\/582"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/comments?post=7875"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts\/7875\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/media\/37840"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/media?parent=7875"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/categories?post=7875"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/tags?post=7875"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}