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.
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:
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.
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.
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.
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.
Question: Does it matter? There's nothing in the site guidelines preventing someone from talking about their own product or service, and half of HN is basically just that. As long as it caters to HN readers (which a technical documentation site more than does) then why does it matter the reasoning behind the post?
Disclaimer: I work for Microsoft. I was not aware of any "PR push", I stumbled upon the story on the front page.
Someone linked to this thread on Twitter, so I thought I'd come in and chime in with some answers to questions HN users have. We've already talked about the original docs launch on HN way back in May 2016.
Eh. When bits about my company wound up on here, someone in the office forwarded it to me pretty quickly.
Word gets around, especially if you're a PM whose job it is to be a public face.
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...
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. ;)
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.
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.
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.
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.).
48 comments
[ 1251 ms ] story [ 3866 ms ] threadAnd 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/
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.
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
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 :)
Yes, that is in the works. As we move more of the dev documentation to docs, F1 will point to the new site.
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)
We have recently moved the blog to our own publishing system, so some of the comments got lost.
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.
https://msdn.microsoft.com/en-us/library/windows/apps/window...
A 'unified technical doc' site that isn't unified - as the Microsoft representative confirms below.
Pointless.
Can you people seriously not see that this is just a preplanned PR push?
Disclaimer: I work for Microsoft. I was not aware of any "PR push", I stumbled upon the story on the front page.
Someone linked to this thread on Twitter, so I thought I'd come in and chime in with some answers to questions HN users have. We've already talked about the original docs launch on HN way back in May 2016.
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...
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. ;)
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.
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.
Thanks for the feedback, we are working across-the-board to make our content easy to discover both through external and internal search indexes.
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...
Can't say anything specific to these samples, but we can figure something out to make sure that legacy content is available.
I am curious how DocFX handles generation of documentation from C++ projects and other things not built-in. Internal plugins?
It's on my personal TODO list :)