Microsoft Docs – Unified technical documentation | Hacker News Reader

Microsoft Docs – Unified technical documentation

docs.microsoft.com

91 pointsmy12344 comments

The new content looks a lot better, but I think it is a shame that this is not using the "MSDN" branding. One of the nicest things about Microsoft documentation is that I can add the term "MSDN" to any random web search and usually get the page I'm after.

Docs PM here.

Thanks for the feedback, we are working across-the-board to make our content easy to discover both through external and internal search indexes.

Fantastic. Maybe hide the word "MSDN" somewhere in the page, just for search engines. Old habits die hard. :)

Slightly off-topic, but would it be possible to reinstate the code samples on the IIS Native Module section[0]? It seemed to go walkies about a year ago and no amount of "Is this page helpful?" feedback seems to get it back. It's quite important because there is little documentation elsewhere on the internet.

[0] https://msdn.microsoft.com/en-us/library/ms693629(v=vs.90).a...

I'll direct that feedback to the team :)

Can't say anything specific to these samples, but we can figure something out to make sure that legacy content is available.

Introduction, circa June 2016:

https://docs.microsoft.com/en-us/teamblog/introducing-docs-m...

All documentation on docs.microsoft.com is open sourced and designed to allow community contributions.

Maybe that was the soft launch? (0 blog comments)

Docs PM here.

We have recently moved the blog to our own publishing system, so some of the comments got lost.

Not a fan of the UI, too nested. Compare two ways to get to the "Welcome back to C++" article.

MSDN: https://msdn.microsoft.com/en-us/default.aspx Click Library -> find the "Visual C++ in Visual Studio 2013" link (ctrl+f for 'c++' or just by looking, maybe get distracted by "oh I didn't know they had doc for that...") -> click it -> click third link in general info https://msdn.microsoft.com/en-us/library/hh279654.aspx

Docs: Click Visual Studio tile (or top level tab?) -> Click "Languages" tab -> Click "Visual C++" -> Click "Languages and Libraries" -> Click "Standard C++ Languages and Libraries" -> Click "Welcome back to C++" https://docs.microsoft.com/en-us/cpp/cpp/welcome-back-to-cpp... (Or if what you're looking for isn't there, notice the expandable table of contents on the left. Compare MSDN which automatically expands the first layer for the context and has easy links to other things.)

The URLs on Docs are nicer. But as someone involved with such stuff at my day job I think the SEO benefits are overblown. ;)

Docs PM here.

Thanks for the feedback. Just want to say that in terms of content architecture, we are working on ensuring that all our content is discoverable - the concerns above are valid and I will direct this feedback to our IA people.

Great that they finally start thinking about documentation which has been a shambolic experience with Azure. However it seems that they are still missing ARM template resources documentation, they provide REST API documentation which kind of sort of helps with the ARM templates but still has a lot of things that are subtly different. So it still means hunting REST API docs to get the idea and then going to the ARM examples repo to find out how it differs.

There's a whole bunch of ARM documentation here: https://docs.microsoft.com/en-us/azure/azure-resource-manage...

And the schemas for practically anything you want to add with ARM are here: https://docs.microsoft.com/en-us/azure/azure-resource-manage... (some even have quickstart versions for you)

And finally I noticed there's a template visualizer now (it was linked off of one of the ARM template pages): http://armviz.io/

Thanks, the second link looked a little promising but then it just does a GitHub search.

A proper documentation would list all possible resources and their descriptions with valid values. There is still nothing for ARM Resources. How CloudFormation can have an excellent documentation and ARM has bits and pieces is a bit weird.

Their QuickStart templates repo is comprehensive but it has no real documentation of the parameters.

You can use the schema to figure out the valid values and descriptions for some of the values, so that might help. I agree that a technical reference would probably help since reading the schema isn't fun.

Doesn't shock me that it's mostly GitHub search since most of our docs are hosted on GH:

https://github.com/aspnet/Docs

https://github.com/dotnet/docs

You can always add a request to the docs UserVoice: https://msdocs.uservoice.com/forums/364242-general-site-feed...

Azure also has its own docs UserVoice: https://feedback.azure.com/forums/217534-documentation

Docs PM here.

Thanks for the feedback, we point to the schema that is pulled directly from the product, but I agree that we can do a better job at documenting it. Will forward it to our Azure content people.

PS: UserVoice is the best way to channel site feedback to us - I check it daily and open bugs based on suggestions there :)

+1 on UserVoice. My team (Application Insights) actively reads UserVoice and the MSDN forum, and I know other teams are just as proactive about reaching out to users.

Note that Microsoft Docs at docs.com is fully different and has nothing to do with docs.microsoft.com...

Great UI...not only do they have the 11 immediately-noticeable centered divs with icons, but the unnecessary and redundant links above them. That's the Microsoft we know and love.

They aren't redundant after you click one. They are just pre-pinned popular topics. No great UX sin

What else would you put on a home page? It's better than a carousel.

What is it unifying if TechNet and MSDN are still around?

Docs PM here.

We are moving content off of TechNet and MSDN and to Docs. Eventually, docs.microsoft.com will become the single central location for all technical documentation shipped by Microsoft.

And thousands of broken links would be born... Are you planning to redirect deep links of msdn pages to the page's new home?

Absolutely. All content that is being migrated will have proper redirects set up, so whenever you are using an old MSDN/TechNet link, you will land on the docs page.

I'll believe it when I see it.

Check it out:

https://msdn.microsoft.com/en-us/library/windows/apps/window...

For .NET a lot of information (eg. Remarks) are now gone which contained vital information. Any plans on adding those back? Examples as well?

Docs PM here.

It's on my personal TODO list :)

This is a wonderful development. And a great example of how DocFX can work in the real world. Even just having memorable URLs is a boon. Thanks!

I am curious how DocFX handles generation of documentation from C++ projects and other things not built-in. Internal plugins?

Yes, we have a number of internal extensions that we use for content generation, since we have a relatively large language & tech spread (e.g. REST, Python, C++, C#, etc.).

Will this be integrated with Visual Studio? Right now, F1 from within the code editor still goes to msdn.microsoft.com.

Docs PM here.

Yes, that is in the works. As we move more of the dev documentation to docs, F1 will point to the new site.

Will there be a way to download documentation from Docs for offline use?

Docs PM here.

There is a way to do that today! One of the features that we shipped is PDF downloads, that enables you to get the entire documentation set for an area in a small PDF file. As an example, take a look under the table of contents on https://docs.microsoft.com/en-us/dotnet/articles/core/tutori...

oh thanks! :)

Will Visual Studio Code docs end up here eventually, as well?

Docs PM here.

Our goal is to put all technical documentation in one place, so we're working with all technical teams across the board to migrate to docs.

Sweet. I like the direction you're going with this.

oh wow https://docs.ubuntu.com/

Reply on news.ycombinator.com