Update NuGet Docs in the Browser with Github

nuget, open source 0 comments suggest edit

We made a recent change to make it easy to update the NuGet documentation. In this post, I’ll cover what the change was, why we made it, and how it makes it easier to contribute to our documentation.

Our docs run as a simple ASP.NET Web Pages application that renders documentation written in the Markdown format. The Markdown text is not stored in a database, but live as files that are part of the application source code. That allows us to use source control to version our docs.

We used to host the source for the docs site in Mercurial (hg) on CodePlex.com. Under the old system, it took the following to contribute docs.

  1. Install Mercurial (TortoiseHG for example) if you didn’t already have it.
  2. Fork our repository and clone it to your local machine.
  3. Open it up in Visual Studio.
  4. Make and commit your changes.
  5. Push your changes.
  6. Send a pull request.

It’s no surprise that we don’t get a lot of pull requests for our documentation. Oh, and I didn’t even mention all the steps once we received such a pull request.

As anyone who’s ever run an open source product knows, it’s hard enough to get folks to contribute to documentation in the first place. Why add more roadblocks?

To improve this situation, we moved our documentation repository to Github for three reasons:

  1. In-browser editing of files with MarkDown preview.
  2. Pull requests can be merged at the click of a button.
  3. Support for deploying to AppHarbor (which CodePlex also has)

With this in place, it’s now easy to be a “drive-by” contributor to our docs. Let’s walk through an example to see what I mean. In this example, I’m posing as a guy named “FakeHaacked” with no commit access to the NuGetDocs repository.

Here’s a sample page from our docs (click for larger). The words at the end of the first paragraph should be links! Doh! I should fix that.

nuget-docs-page

First, I’ll visit the NuGet Docs repository (TODO: Add a link to each page with the path to the Github repository page).

nuget-docs-github

Cool, I’m logged in as FakeHaacked. Now I just need to navigate to the page that needs the correction. All of the documentation pages are in the site folder.

Pro tip, type the letter “t” while on this page to use incremental search to search for the page you want to edit.

Here’s the page I want to edit.

page-with-fork-this-button

Since this file is a Markdown file, I can see a view of the file that’s a nice approximation of what it will look like when it’s deployed. It’s not exactly the same since we have different CSS styles on the production site.

See that blue button just above the content and to the right? That allows me to “fork” this page and edit the file. Forking it, for those not familiar with distributed version control, means it will create a clone of the main repository. I’m free to work and do whatever I want in that clone without worry that I will affect the real thing.

Let’s click that button and see what happens.

github-markdown-editor

Cool, I get a nice editor with preview for editing the page right here in the browser. I’ll go ahead and make those last two references into Markdown formatted links.

When I’m done, I can scroll down, type in a commit message describing the change, and click the blue Propose File Change button.

enter-commit-message

Once you’re happy with the set of changes you’ve made, click the button to send a pull request. This lets the folks who maintain the documentation to know you have changes that are ready for them to pull in.

send-a-pull-request

And that’s it. You’ve done your part. Thank you for your contribution to our docs! Now let’s look at what happens on the other side. I’ll put on my project maintainer hat and visit the site. Notice I’m logged in as Haacked now and I see there’s an outstanding pull request.pull-requests-nuget-docs

Cool, I can take a look at it, quickly see a diff, and comment on it. Notice that Github was able to determine that this file is safe to automatically merge into the master branch.

merge-pull-request

All I have to do is click the big blue button, enter a message, and I’m done!

confirm-merge

It’s that easy for me to merge in your changes.

Summary

You might ask why we don’t use the Github Pages feature (or even Git-backed wikis). We started the docs site before we were on Github and didn’t know about the pages feature.

If I were to start over, I’d probably just use that. Maybe we’ll migrate in the future. One benefit of our current implementation is we get that nice Table of Contents widget generated for us dynamically (which we can probably do with Github Pages and Jekyll) and we can use Razor for our layout template.

The downside of our current approach is that we can’t create new doc pages this way, but I’ll submit a feature request to the Github team and see what happens.

So if you are reading the NuGet docs, and see something that makes you think, “That ain’t right!”, please go fix it! It’s easy and contributing to open source documentation makes you a good person. It’s how I got started in open source.

Oh, and if you happen to be experienced with Git, you can always use the traditional method of cloning the repository to your local machine and making changes. That gives you the benefit of running the site to look at your change.

Found a typo or error? Suggest an edit! If accepted, your contribution is listed automatically here.

Comments

avatar

12 responses

  1. Avatar for Khalid Abuhakmeh
    Khalid Abuhakmeh October 28th, 2011

    Very cool, which brings up another point. Why is codeplex getting no love from Microsoft? Have they abandoned it?

  2. Avatar for Ben Aston
    Ben Aston October 28th, 2011

    Excellent. GutHub is currently by far and away the best code collaboration platform. The move to use GitHub for Microsoft efforts should be wider reaching.

  3. Avatar for Steven Harman
    Steven Harman October 28th, 2011

    "Open it up in Visual Studio..." <- Well THERE's your problem! :)

  4. Avatar for Adebisi Foluso A.
    Adebisi Foluso A. October 28th, 2011

    Open it up in Visual Studio..." <- Well THERE's your problem! :)
    Try:
    http://gitscc.codeplex.com/releases/view/46589
    visualstudiogallery.msdn.microsoft.com

  5. Avatar for Ian Patrick Hughes
    Ian Patrick Hughes October 28th, 2011

    HA!
    GitHub is to code collaboration as Facebook is to social networking services. Well, except, they just keep doing everything so right.
    This is really great and exciting to see that you guys are embracing it this way.

  6. Avatar for Brian Vallelunga
    Brian Vallelunga October 28th, 2011

    While this is nice, why not add this feature to Codeplex?

  7. Avatar for haacked
    haacked October 28th, 2011

    You'll have to ask the Codeplex team. I'm not on that team.

  8. Avatar for hazzik
    hazzik October 28th, 2011

    Is this a miracle? Microsoft makes steps to run away from NIH syndrome?

  9. Avatar for Joshua Flanagan
    Joshua Flanagan October 28th, 2011

    Github's business relies on offering an awesome code collaboration experience. Microsoft's doesn't. Don't know why people would suggest sticking with codeplex.
    The nuget team continues to impress me for breaking out of the Redmond reality distortion field and embracing the best tools and techniques used by the rest of the open source software community.

  10. Avatar for Magesh
    Magesh October 30th, 2011

    Oh ho!! Phil is using CHROME... ;)

  11. Avatar for Mike
    Mike October 31st, 2011

    "You'll have to ask the Codeplex team. I'm not on that team."
    Can you influence them in some way? Mercurial on Codeplex is great, but the pull process is not.

  12. Avatar for drewid
    drewid November 25th, 2011

    Putting on my "user" hat and not "project maintainer" hat, codeplex is way, way, way more user friendly to use than github.
    Codeplex actually has a usable interface that looks good and has links to useful content -> documentation, discussions, issue tracker, downloads, source code, etc - gihub doesn't. Also you actually land at a frickin home page! I can find out what the hell is up with the project, what it is, usage, etc. Github dumps me at the code page which usually has little or no info.
    Every time I have to use a github site I groan as it is so stark and usually bereft of any content at all regarding what the project is. The design is so minimalist it might as well have been done by a blind unix programmer.
    OK rant, over.
    If the development side of github is so much better hopefully github can get its act together on the usage/community side - currently it sucks. Conversely, what specifically does codeplex need to do on the project developer side?