Contributing to ASP.NET 5 Documentation

If you’re looking to learn ASP.NET 5, the best place to start today is the documentation site at docs.asp.net. It’s hosted on ReadTheDocs and the source is all in GitHub (/aspnet/docs). Since it’s all open source, you can contribute to the documentation yourself, which is a great way to learn ASP.NET 5 and help your fellow developers. I’ve created a short video that walks you through the process:

Check it out and let me know what you think.

  • Sean

    Thanks for the great overview Steve. It’s a great process but there’s one big thing that’s glossed over in the contrib guide: how are the RST code-block file/line references handled over time as the source repo changes? Is this process not able to be used with a live code base (and only examples)?

  • ardalis

    It’s definitely easiest with fixed samples. There is also api doc support if that’s what you’re looking for (see here for example: https://docs.asp.net/projects/api/en/latest/ ).

    Using code blocks will decouple your docs from your codebase, but then of course they can get out of sync. There are other options for defining your code blocks, but at the end of the day you’re not going to get away from having to update your docs if your code changes substantially.

    More on literalinclude and code-block: http://www.sphinx-doc.org/en/stable/markup/code.html