Introducing docs.microsoft.com | Hacker News Reader

Introducing docs.microsoft.com

docs.microsoft.com

249 pointsyread187 comments

From TFA:

"Shortened Article Length

Another common piece of feedback was that our content at times can be overwhelming because of its length and that long articles are more difficult to navigate and find what you’re looking for. To address this, we’ve broken down many longer articles into smaller logical steps and provided Previous and Next buttons at the bottom of articles to navigate between steps in a multi-part tutorial as shown below."

Sounds like a race to the bottom. I very much prefer long single-page articles.

can be overwhelming because of its length

This makes no sense at all, even if you think people's attention spans have shortened. You see the same amount of content at once regardless of whether it's been paged, unless your browser window is ridiculously large or the content has been literally split into paragraph-per-page levels of fragmentation. You'll eventually get to see all the same content, but you have to spend more clicks (and possibly scroll) to get to the part you want instead of just scrolling. I have the same gripe with some other sites that love click-toggling sections (especially when there is no "expand all" button, or expanding one collapses the others, or even worse --- they default to collapsed without JS.)

Maybe it's the result of some stupid "engagement" metric that awards clicking around? That's completely counter to the point of documentation; it's not supposed to require much interaction, it's supposed to be something you passively read while doing whatever it is you need to with the information you've consumed.

> Maybe it's the result of some stupid "engagement" metric that awards clicking around?

It seems it's exactly this (I see I'm linking to your another post, but it really deserves to be prominent):

https://news.ycombinator.com/item?id=11627448

fyre.co Livefyre "The Leading Content Marketing and Engagement Platform" (a site slogan by that company)

[Disclosure: I work for the team that built docs.microsoft.com]

Thanks for the feedback, and we went through a lot of customer feedback already on this. I'll try to be brief in a response

- A good example on why - For our documentation we clearly saw customers jumping around content trying to find the part of the article that helps them. Depending on the article (see point #2) very few people read from beginning to end. A good example here is that instead of having separate articles on how to setup iOS, Android and Windows phone devices with Intune, the previous articles had that as part of a much later article. If an admin who's company has standardized on Android, they want just the Android content, they don't want to have to sift through iOS/Windows troubleshooting to get to the Android setup content. For SEO, it's also much more likely that they'll find the solution by Googling (with or without Bing) to something like "Setup Intune Android" and go directly to the page that takes care of just that task. For developers, we face the same problem where some articles include multiple langauges and code samples are duplicated. Instead of doing that, we would break the article into pieces by language.

- Another key reason is not all content is built the same. We'd get feedback that many of our competitors have a much simpler "Getting Started" tutorial, while ours would be much longer and we'd get feedback that it seems more complex or overwhelming. When you are just starting off, "Hello World" is a lot better than War & Peace. It's about thinking about the right level of content for the task our customers are going through. In some cases, it's fine to have one long article.

- We will also provide the option for customers to have all content together versus having content broken into separate pieces and made available for offline. Customers want both.

- The reason we called this out is that the previous architecture doesn't not even have this as a capability.

I hope this helps give some context on the decision and thanks for the feedback.

One thing I beg of you:

Don't break links to old versions of documents!

(I realise this requires building a redirect forest. But we're talking 20 years of MS documentation.)

[Also MS employee that works on the docs.microsoft.com team]

No, we will not break links. We are doing graceful redirects from MSDN/TechNet to the new site.

Thanks for that. I have come to expect all MSDN links to rot almost immediately, and it'll be nice to see that stop happening.

How about building in a direct way to report errors and issues with the docs that actually is fixed and checked? You can't even get a working MIM 2016 AD sync setup right now with the numerous errors in your docs (https://docs.microsoft.com/en-us/microsoft-identity-manager/...).

It's frustrating to say the least and I'd prefer we not even deploy the product.

> For our documentation we clearly saw customers jumping around content trying to find the part of the article that helps them.

Isn't that what anchor tags are for? You can share them in URLs...

Their solution appears to be actually worse than the initial state, if they simply automatically split the long pages and add "prev - next" buttons.

The proper solution for them is to look at Wikipedia as an example. Tables of contents in longer articles, manually introducing the new topics or reorganizing when it's reasonable. And it's not something that can be automated.

Automatic splitting of long pages to shorter ones is good only for "we get money for clicks" media but not for a repository of knowledge with serious intentions.

Not to mention, it makes it harder using Ctrl + F to find information.

This ^. I often find myself clicking on "print" links on sites to make things show up on a single page so I can locate things quickly.

It would be nice to have a long form option, especially when intending to CTRL+F the page

It makes it much easier to collect metrics on what people have read.

Agreed, this change seems like a step backwards. Docs aren't about page views.

I think the main issue with documentation for Microsoft products/APIs is that the content is spread out on a large number of different Microsoft domains which makes it inherently difficult to find something. I have also often found (after using google to find the relevant article) that the content is either out of date or not relevant anymore.

Adding yet another site to the list of sites which might or might not have up-to-date content is not going to fix that issue. What they need is a central, properly searchable and well-maintained repository that spans all of their products.

Depending on what you're looking for, there's usually only two you need: MSDN[0] and TechNet[1].

[0] https://msdn.microsoft.com/library [1] https://technet.microsoft.com/library/default.aspx

You confirm the problem in your response:

"usually"

"only two"

That means that Google.com is still needed as the front-end to MS documentation. Ergo, it doesn't matter how many domains they use to host their documentation.

Not to mention search on MS sites essentially doesn't work (unless something has changed).

Agree. Actually I'd already be happy if they stopped moving stuff around for no reason. I get "This object has moved" or worse "This object no longer exists" or just a redirect to some generic "Download Windows 10" page all the time on Microsoft documentation sites. :(

[Disclosure: I work for the team that built docs.microsoft.com]

Thanks, this is great feedback and something we totally agree and want to fix. We recently created a redirection service, which historically did not exist on MSDN/TechNet so that when content moves, we can properly 301 redirect content to the correct place. This will help for net new content that moves, but as you correctly point out, we still have a lot of work to do for existing content.

Thanks again for the feedback!

I thought biggest improvement to the MS website, MSDN and technet included, would be simply to disable the incessant demands for feedback on the webpage or surveys.

Would you like to take a short 25 minute survey? You visited this site 25,000 times previously and we have asked each of those times, but maybe this time you will change your mind and answer the survey.

[Disclosure: working on the team that built docs.microsoft.com]

We are fixing that. Thank you for the feedback!

Thank you, I sent this same feedback because on some configurations it would use almost 20% of the screen.

The login proxy (where it checks if you are a user or not and if you should login to track you) really sucked too, I would just use the docs in private browsing mode and it would be 10x faster.

Thanks for your hard work, the new docs look excellent.

The real reason I shop on Amazon? Every other website spams those damn surveys when all I want to do is browse products.

At $DAY_JOB we have various document (or rather, knowledge) repositories -- a mostly-abandoned-but-still-useful-often-enough-to-not-ignore wiki, the obligatory but overwhelming salesforce, personal (silo) collections of email lists/archives, a semi-public knowledge base, a half-hearted attempt at moving internal mail lists into yammer, various product guides (PDF's), a public-access user forum, an LMS, and probably a few others I don't know about. It is precisely as easy to search for information as you'd assume.

Last year we embraced Sharepoint - with expectations of replacing much of the above. (It didn't.)

Evidently no one uses Sharepoint as a way of presenting documentation to the world - let alone using the wiki-like features - not even Microsoft. What's the opposite of NIH syndrome?

Situation: There are 14 competing information stores.

14?! Ridiculous! We need to develop one universal store that covers everyone's use cases.

Situation: There are 15 competing information stores.

Solution: Move things over from one into the blessed solution, and then kill the other one. Repeat as necessary. Accept that nothing will cover 100%

Sometimes you have to push to fix the process

You always have to push to make changes like this. You have to allocate ressources to migrate, and while it may save money in the long run, not all management people understand or want to pay for it.

Quite often the only push that can fix problems like this is push from upper management because no matter what someone is going to be upset and will sabotage or drag it out forever.

A lot of companies do use SharePoint that way (including Microsoft), they just heavily modify the look, and in some cases (Microsoft kb articles, as an example) have publishing flows to export static pages to be cached by CDNs.

I don't doubt some do this - I don't know how you'd tell from looking at a (heavily skinned) site. But it sounds like MS hasn't done this here - they've designed and built a new documentation repository.

More power to them, btw. Most (HN) people's complaints sound fairly cosmetic - easy enough to adjust. Sensible URL's are probably worth the cost of conversion alone. But my point is/was that this doesn't appear to be a re-skinning of Sharepoint - it looks like (yet another) bespoke DMS.

> our existing content infrastructure TechNet and MSDN... are built on a 10-15 year-old brittle codebase

I just assumed they meant Sharepoint there.

Ugh. I'm all for modernizing msdn, but those mouse-over comment bubbles cause a the text underneath to shift - that's just really, really annoying. Mousing over the text causes everything to jump around.

Also, the marked-text context menu: that only works within a single paragraph. Cross over to the next and it's not showing any more.

Agree, it's so irritating that I stopped reading the article and came back to hacker news to read the comments..

I am wondering how google (mentioned as an offset to bing) is going to handle the availability tweeking and facebooking feature. It will be interesting to see if my searches now reference some persons personal collection of data and take me away from page source. Search engines are all about recent/modified content and might go to the less official/slightly modified sources. The search engine communities are full of intelligent people, but I still can't get the same 5 pages from stack overflow showing up when I have a problem, no matter how I change the search terms. I usually end up going to the site and then going to the reference link in the answer.

Livefyre sidenote feature breaks selection and copy/paste on iPhone - aside from being completely useless in first place.

Sending snippets of docs via email and other means is key - and is so much easier than signing into a third party service, using some lame social share feature, and then trying to find your contact there instead.

Aside from that, new layout looks nice!

Replying to self: tables are completely broken on mobile too - eg https://docs.microsoft.com/en-us/multi-factor-authentication... and scroll to 'options' - it's about 5 CHARACTERS wide on iPhone 6 :)

Well it looks quite horrible on desktop as well

I am glad to see they acknowledge MSDN is bad. I fear they will make it worse but well, we'll see. Microsoft has been surprising these times.

Just try to get Google or Apple OSes documentation.

MSDN is the best documentation I ever seen from OS vendors.

Not to mention the mainframe, commercial UNIX and embedded real time OSes, even worse than those mentioned above.

redhat.com/docs and (back when Sun was a thing) docs.sun.com were great.

Where is the Red Hat documentation about the programming languages, respective libraries and IDEs delivered in a Red Hat ISO?

This one looks very poor versus MSDN content.

https://access.redhat.com/documentation/en-US/Red_Hat_Enterp...

I'm pretty sure they rely on the respective upstreams to provide those.

Red Hat's OS docs are very good. I'm not sure it's their job to document what you're asking for.

If we are comparing them to MSDN quality, it is.

MSDN documents everything that Microsoft delivers to Windows developers, OS, programming languages, frameworks, IDEs, system administration,knowledge base, magazines and books.

Interesting choice of domain name. Coming from docs.google.com, I almost thought this was Office 365.

Also, docs.com. A Microsoft product.

Oh no. It pops up a quick menu when I select text, like Medium. The problem is that I'm constantly selecting the lines I'm reading. :(

Edit: Also, it's extremely narrow. On my 32" 4K display, 70% of the screen is empty. And the font is too think. And stuff keeps moving/jumping when I'm moving the mouse cursor.

I want 1998 back.

> The problem is that I'm constantly selecting the lines I'm reading

I'm glad to hear I'm not the only one! I compulsively select random blocks of text: select up, select down, repeat. I definitely get annoyed with the popup-menu-on-select feature of Medium, but I feel I can hardly blame Medium for my random, compulsive habit.

I share this "pain".

I have the unshakable habit of triple-clicking a paragraph to highlight it to serve as a mark of where I was at when i need to interrupt reading.

I also have the same ehabit. I a glad I am not the only one.

Interesting little curiosity about how triple-click implementation varies in some popular software =)

https://en.wikipedia.org/wiki/Triple-click

Me too, anyone know why this is a thing? Such a common twitch... does it help reading?

I have acquired this habit from the 2 years I've spent playing Starcraft : Brood War and Starcraft 2 semi-competitively.

In the game you have to select units by dragging a box around them, and that habit has carried over to selecting text on the screen in pretty much every computer application.

I know that probably doesn't answer your question, but that would probably require a neuroscientist. It doesn't help me read personally, it just seems to be one of those repetitive tasks that slightly autistic people do.

Some of my coworkers share this habit as well, and they've never played RTS games, so it's acquired in different ways.

I do not have any data on it (1) but I think it's like moving a bookmark across the page as you are reading: it makes it easier to jump from the end of one line to the start of the next one.

(1) not even on the claim that that bookmark has that effect.

It's called meta-guiding

In french I say "astigmate". Either vertical or horizontal lines are blurred. Plus maybe you're tired. Anyway you can follow straight lines and you select something to add a visual clue of your position. "It's all because of" modern designers and their featureless screens.

I too am a highlighter

I too am a highlighter.

I too am a highlighter. We should form a self-help group.

I'm in.

I only learnt that the other day. I read that double clicking selects words, so I had to take it one step further.

No, clicking four times doesn't select the whole page.

I sometimes select the current line that I am reading. This helps me to quickly figure out the start of the next line when I am finished reading the current one.

So what do you guys think of HN? I get frustrated by how if I drag the selection down on HN comments, the selection will "hop" up at certain points. It's very aesthetically unpleasing, but I just need to click and drag select whatever I'm reading.

fwiw, I believe this is due to HN's archaic table-based html layout, as opposed to some javascript code like on medium and this new ms docs site.

This is it.

It has to do with border-spacing between table cells -- when you select text that runs into the border-spacing, it resets the selection to go from 1) original cell 2) start of the table 3) next cell.

With more sane styling (ie: setting border-spacing to 0), the selection won't jump to the start of the table.

I don't mind HN, you can get all sorts of pleasing patterns of highlight by dragging down nested comment hierarchies. Extra satisfying when you get the darker 'double highlight' and you can make it pop by wiggling your fingers a bit.

This is just heaven here: http://imgur.com/asQy8v3

Look at all those lovely lines and right angles.

Hey, don't sell yourself short. It's akin to using your finger while reading a book. It helps you to keep your place and focus, which the highlighting in browsers works even better for. So I wouldn't necessarily call it a quirk that Microsoft doesn't have to account for. Webdevs should really stop overriding browser defaults in detriment to the user experience. (nothing is more evil than clipboard hijacking)

I wonder what proportion of the web population does this, and if they have a demographic skew. I think I remember starting this back in the late 90's in response to a combination of extremely janky, inconsistent scrolling and tiny monitors which made me easily lose my place while reading a long article. So I'd highlight a section of text before scrolling as a marker, which developed into a compulsion over time. The constant clicking drives my friends and coworkers nuts.

I used to do this. Switching to using a MacBook full-time fixed that habit for me. Even when I connect to a big monitor, I use a trackpad, not a mouse. Harder to compulsively highlight with that thing.

Enable 3-finger drag on the trackpad and relive the old days.

Don't forget the 11-finger tap.

Damn you. :p

Not only Medium, there are lots of websites like this. BTW It seems there's lots of us compulsive clickers here on HN :)

I used to do this and then stopped once I switched to Linux where selecting text put it on a clipboard automatically.

I suspect it's related to some patterns when reading books, like putting a bookmark below your current line and moving it down, or following your current position with your finger.

> On my 32" 4K display, 70% of the screen is empty.

Totally agreed on your other points (particularly about animations on selection) but as the article mentions, eye tracking repeatedly shows people have trouble reading very wide text. Also many people use large monitors to have multiple windows, rather than a single window maximised.

I stopped maximizing my browser window a long time ago, and I only have a 27" monitor. It's just not comfortable for me.

I prefer to have my browser maximized, though it's true too wide text is not easy too read.

I've noticed also that I don't like to read text that starts on the left of the screen.

The solution that works for me is to install a sidebar (on Firefox, AiOS add-on) and if text is too wide or starts too much on the left, I enable and resize sidebar accordingly :)

> eye tracking repeatedly shows people have trouble reading very wide text

Yes but to optimize for larger screens, the correct thing to do is to scale everything up (fonts, spacing, etc) in a responsive manner.

The amount of text content per line wouldn't change much, it would just fill up the screen better instead of using the same tiny font size you'd use for a 13inch screen @ 1080p on a 32" 4K display.

Scaling up only works to a certain point. Not every screen is a phone screen and should suffer from the same amount of visible text. If I scale a page to a good line length I end up with text so comically large that only a single paragraph fits on the screen, if at all.

When lines get longer you either have to increase the leading, or font size, or shorten the lines to retain readability. Personally I hate having to detach every other tab from the browser just to change to width to something that's readable. In that sense I much prefer the content to have a maximum width beyond a certain viewport width because it's the only viable option to still have text that is readable.

No, to optimize for larger screens you simply acknowledge that it's the user's machine, not yours, and do nothing. The user will make their own choices. If they want to open multiple windows so they can read multiple columns of text, they will do that. If they want to make the text bigger, they will do that. If they like it the way it is, they'll leave it alone. Not your problem to solve.

A better option is to expand to multiple columns, like Newspapers discovered centuries ago.

That only works when your content fits on a screen because it messes with the scrolling-based nature of the web (or screen content in general – just picture how awkward it is to read an A4-portrait multi-column PDF with fit-to-width on screen).

Personally, I like well-columned stuff switching to scroll horizontally.

(It's one of the things I loved about the design style of Windows 8 apps that has been lost in the Windows 8 hate, and admittedly was a part of the Windows 8 hate, because people don't respect a good horizontal scroll of columnar reading material, sigh.)

I happily browse the Web at 125% on a 27inch monitor because I like pages to be large, but if pages made double width windows have double size content it would be like sitting directly in front of a TV.

As a substitute for 1998, a simple userscript blocking all text-selection events could do the trick. One of the great things about the web is that you can choose how to consume it - publishers are essentially powerless to prevent you building your own view on their data. Adblock, readability, etc. It can be easy to forget sometimes.

If it were 100% wide on 4K, how would your eyes scan the text? It's useful for illustrations (graphics), but I haven't met a person yet who can read wide text as efficiently as one or more narrow columns.

I've given up completely on landscape for monitors. I've rotated my two monitors to portrait. It works for websites, but it's also ideal for programming (no more looking through a letter box at the code), reading documentation and pdf pages.

I've gone for main in landscape and portrait one on the left - the only issue with portrait can be the height, I find myself having my browser starting half way down, with the top section reserved for things like a console window that aren't being looked at constantly (would be great to be able to fullscreen video on just that bit too).

What type of panels and implementations (monitors sold) work well in portrait mode? I've tried it once and I saw an odd pattern that wasn't very comfortable to look at.

TN panels are usually horrible, as they have (in landscape mode) a very limited viewing angle up or down before colours start to shift or parts of the screen appear way darker than others.

IPS panels should work without a problem in both landscape and portrait mode.

I use IPS and VA panels, but I wouldn't be able to tell what panels it was when I had the bad experience. I'll try it again, but not every IPS or VA panel is good either.

I wish this worked for games, I'd totally be a portrait user.

A triple monitor setup with 2 side monitors in portrait mode seems to be optimal these days.

That way your primary monitor can still be used to watch media and play games in the "standard" widescreen format, but your code and browser can readily be viewed on the sides.

For ergonomic reasons your work should be in front of you. If you're staring at a side monitor long term that'll wreak havoc on your neck.

Just run the games in windowed mode and you can generally change the size to however big you want.

sure but the UI is generally written to be a horizontal layout.

There are other stuff you can store on the left/right sides, especially when it's a documentation site. Typically a nice hierarchical ToC.

I've seen this claim repeatedly but it doesn't match my personal experience. I've taken to using a user stylesheet that disables max-width on all elements. It makes my subjective web experience a lot nicer.

I resize the window down to where it's more comfortable to read.

If it weren't for tabs, a window resize could help there.

> And stuff keeps moving/jumping when I'm moving the mouse cursor.

Yes it's quite bad on that blog post, but if you check out an article [1] it doesn't suffer from that problem. Still has the selection-reader [2] problem, though.

[1] https://docs.microsoft.com/en-us/remoteapp/remoteapp-whatis

[2] https://blogs.msdn.microsoft.com/oldnewthing/20150528-00/?p=...

[Disclosure: I'm on the team that helped build the site]

Yes, this is a bug and something we will fix, thanks for calling this out :)

the text in [1] is not justified, that seems to make the comment icon behave differently.

It goes to the right of the paragraph in that case instead of the last sentence of the paragraph.

Hover over an image and watch it change the layout.

Use NoScript or equivalent to block scripts from the domain fyre.co. This prevents that annoying menu from popping up.

> Livefyre: The Leading Content Marketing and Engagement Platform

Looks like something to block regardless of whether it creates annoying menus. Is anyone else a little surprised (and perhaps repulsed) by Microsoft putting semi-shady 3rd-party scripts like this on their site? This seems completely opposite of what the Microsoft I knew would do.

I've seen them used to power comments on some sites, which is why I left them enabled after I installed Ghostery. I might reconsider if I see them putting junk into other websites though.

Looks like you can block just //cdn.livefyre.com/libs/sidenotes/v1.3.3/sidenotes.min.js to get rid of the inline popups.

As of yesterday they have been acquired by Adobe.

>I want 1998 back.

I'd be happy with 2011, just before the Metro-inspired redesign of MSDN hit.

Compare:

http://web.archive.org/web/20111228110049/http://msdn.micros...

http://web.archive.org/web/20130422112102/http://msdn.micros...

http://web.archive.org/web/20150102192514/http://msdn.micros...

I very much prefer the first design too.

There seems to be some plan to use less and less of the screen. I keep looking at wordpress templates and almost all of them want to use about 1/8th of my screen width which is terrible

Also a small "add comment" icon pops under each paragraph when hovering, making entire paragraphs jump up and down as I scroll down the page, it's very distracting.

The icon for adding a comment to a paragraph when there is none also causes the rest of the page text to reflow. If this is a preview of what's to come, they've migrated to a 2016 appearance and brought along all the clunkiness of the old MSDN. Kudos.

> Oh no. It pops up a quick menu when I select text, like Medium. The problem is that I'm constantly selecting the lines I'm reading. :(

I do the same thing when reading text and HATE websites that do this, the solution I've found is to just use uBlock Origin to block annoying web elements like this. You can do the same, just add the following filters:

docs.microsoft.com##body > .lf:nth-of-type(7) > .lf-active.lf-selection-popover.lf-popover > .lf-popover-content.lf-thread-content

docs.microsoft.com##body > .lf:nth-of-type(7) > .lf-active.lf-selection-popover.lf-popover > .lf-popover-arrow

or just docs.microsoft.com#.lf-selection-popover

Is there a generic way to kill the function every website that ever tries to do this to me?

> 70% of the screen is empty

Welcome to the last few years. I thought, when i bought a 24 inch monitor, I'd be using all of it; instead I'm minimizing Firefox so that sites don't look silly. I guess when you're using technology as badly designed as that used to create/display websites anything harder than justifying text and images becomes a nightmare to develop and support.

> Also, it's extremely narrow. On my 32" 4K display, 70% of the screen is empty. And the font is too think. And stuff keeps moving/jumping when I'm moving the mouse cursor.

Why maximize a browser window on such a screen? Three or four windows side by side would take advantage of it.

I don't remember 1998 too well, but I read the article formatted like this http://m.imgur.com/yWTv9Xz and I still find it preferable to the original.

Ha! So a lot of us have that strange problem! :) And I hate it too when websites do funky pop-up stuff on text selection. But somehow, I don't see that problem on this website. Which browser are you using?

I see this on Firefox on Win10. And you have to hit the back button twice to go back, which happens on a lot of Microsoft sites.

Edit: looks like it's being served from fyre.co, which might be blocked by adblockers?

> And you have to hit the back button twice to go back

Could browsers not be smarter about this? If I'm on page A and I click a link X that redirects to B, when I click back I expect to go back to A, especially if X still redirects to B.

Browsers are already smart about that, but they also allow websites to override it, which is kind of important too. And then they can mess it up.

Strange. I'm using Firefox on Win7 here, but it shouldn't have been Windows difference. Will check when I go home where I have Win10.

Oh, I found out - I was looking at a following link from the original page (https://docs.microsoft.com) - which didn't have the problem. It's there on the HN linked page. These days I fix all of these annoying pages using uBlock Origin's "Element Picker mode" and hiding them.

Block livefyre.com javascript and they stop appearing

Hold the button while you read, the popup appears on mouse button up and not on the press itself.

It does for me anyway, must depend on browser and device.

I really hate the popup thing.

NoScript it into oblivion or cut it out with a Greasemonkey scalpel.

What monitor do you have?

I thought Microsoft Open Sourced their docs to Stack Overflow a long time ago?

Hard to believe I had to scroll this far down the comments to see this sentiment. I've been working with .NET since 2001, and I avoid MSDN because most "documentation" is nothing more than class definitions and member signatures pulled straight from the compiled code or XML documentation. There tends to be no useful information like detailed samples, possible use cases, how the class interacts with other related classes, etc. If I just want to see signatures I can decompile the class with ReSharper. Make it more like Stack Overflow and they'll have some converts.

I would prefer if MS opened up their documentation and made it available for offline usage. The current options for that are hopelessly inadequate with (arbitrary) limits on the amount of data you can export. Now we get this crapscript laden fancy thing with only content from the marketing division. Not impressed.

All Documentations for Docs are available on Github. They are not all in the same repo, but grouped by topic.

Azure? git clone https://github.com/Azure/azure-content.git

Azure RMS? git clone https://github.com/Microsoft/Azure-RMSDocs.git

...

Maybe I'm just losing my eyesight, but does anyone else find that font impossible to read?

I also find it hard on my eyes. Looks like it's "Segoe UI" embedded via web fonts.

If you compare their screenshot: https://docs.microsoft.com/teamblog/content/images/2016/05/D...

To one of mine: https://imgur.com/rFwTqUW

It's not even close.

Edit: Seems the "blog" portion is very different than the actual docs: https://imgur.com/YKvFxCh

[Disclosure: I work for the team that built docs.microsoft.com]

Thanks folks, we had Segoe UI Light on the blog and have switched it to use the same font as our docs!

Awesome! It's very encouraging to see your comments here, reminds me there are humans in the tech ;)

docs.microsoft.com looks like it will be a very nice upgrade.

Mine looks similar to yours but even a bit lighter than your screenshot, it's really totaly unredable even when selecting the text.

It looks like they are using segoe UI Light with a bad contrast (background too white, text too dark). Their visual design needs work.

Ironically I think these kind of thin font faces render worse on Windows than on both OS X (Quartz) and Linux (FreeType). An odd choice given their rendering engine's limitations, but hey, maybe they are just expecting people to move on to HiDPI displays where I think rendering engine deficiences are often taken care of by raw resolution.

It's hard to read for me too. I think it's because too little contrast for such thin font. Main page is bad too, especially this blue boxes.

They have a toggle for light/dark themes (dropdown in the right hand col) if it helps?

Some CSS tweaks that make it slightly more bearable (at least on my 1920px wide display)

  /* disable social sharing buttons */
  .lf-selection-popover,.lf-thread-btn{display:none;}
  aside#social{display:none;}

  /* make sidebar thinner and content wider */
  @media only screen and (min-width: 1024px){#sidebar{max-width:20%;}}
  @media only screen and (min-width: 1024px){div#main{max-width:80%;width:auto;margin:0;}}
  body>div.container{max-width:none;}

  /* make blog post wider */
  article.post{max-width:none;}

Are you sure making things wider actually makes it easier to read? Very long lines have make it hard for your eyes to track the start of the next line when you've reached the end of one. This is backed up by solid research, and is the main reason why books, magazines and a lot of websites have the width that they do.

Not all text is about maximum readability at the expense of everything else. If there is a long doc that I need to scan to find out where the useful bit of info is, I want to see more on the screen, even if it goes against some study saying I don't want to. If I'm reading every word of something, maybe the oft referenced studies are valid. In any case, I would certainly prefer that I had the choice to lay it out how I prefer. When making a doc platform like this, it doesn't seem like a ton of work to cater to different opinions, even if they think the customer is wrong.

I like how they're boasting about how much effort it took them to figure out people want something simple and easy to use.

More like one person or group spent a lot of effort on convincing their boss that people wanted this.

Nice, I've always found msdn to be a bit hard to navigate through.

Yes! When the easiest way to something on a web site is to ask Google (or some other search engine) for it, something is very wrong.

Well it would be if there weren't so many broken links to MSDN and Technet. I don't have to use those sites any more, but it always seemed like they were constantly changing the urls for stuff. Even links from product help pages or error messages were usually always broken.

Their search capability simply sucks. Unlike google, it seems knowledge from Bing doesn't seep to other parts of the company. Windows store search also sucks. It can't handle misspellings the way Youtube and Chrome store can.

It's not just the builtin search, the way the content is organized always seem be out of line with the way my brain works.

As a reference, take a look at (if you're not familiar with it already) at PostgreSQL's manual[1]. With Postgres, I don't need to search, I can (nearly always) find what I need by scanning the table of contents by eyeball. Also, I can download the whole thing as a PDF for offline reading (or printing if I wanted to).

This is an example of the standard Microsoft should aim for. And that's just the first example I can think of off the top of my hat. FreeBSD has a great manual, too, and last time I looked, the JDK also came with very good - and well-organized - documentation. I don't think it is hard to do per se, just very tedious, but Microsoft certainly has the resources to do it if management makes it a priority.

I am sorry for ranting a little here, but the state of Microsoft's documentation is very disappointing in light of the resources they have; when I was a Linux newbie and made the mistake of asking a stupid question on a discussion board, I got flamed rather hard about not having read the documentation. I then replied - my second mistake, I guess - that apparently to Unix people, "user friendly" means "comes with more documentation than you'd ever want to read". One of the flamers replied - in a very matter of fact tone - that, yes, documentation is always good, because without documentation you're screwed eventually; with good documentation, no matter how complicated and nasty a program is, at least you have a chance. It took me many years to understand the wisdom in those words, but I think I only came to really appreciate them since I became a Windows admin.

[1]http://www.postgresql.org/docs/9.4/static/index.html

Couldn't agree more. I've always considered PostgresQL's documentation the finest of any software I've used, OSS or not. Many years' experience with all kinds of software convinces me it's nearly a law of nature: the quality of a project's documentation predicts the quality of the software itself.

However I'm pretty sure writing excellent documentation must be a very hard task, otherwise it wouldn't be such a rarity. Of course, Microsoft has the resources to do it, but the level of resources required to produce and maintain surely must be decidedly non-trivial. Reasonably, we could conclude they think it provides poor ROI.

We might well beg to differ on that point, and worth saying how much their inadequate documentation reflects the quality and utility of their products.

I think postgres' docs work quite well as a reference documentation. But in my opinion they're quite bad at introducing users to postgres/SQL/databases, including important operational tasks like backups.

In some respects that's true, though the docs do contain a lot of patient explanation at a pretty basic level.

I wouldn't exactly call it a tutorial but it did teach me a great deal about SQL when I started using the db > 15 years ago.

New standards and features have made the program more complicated over time, so periodically I need to study up on these topics. More than a few times, it's been really useful to have that "beginner level" info re: stuff that's new to me.

But like you say, not all subjects are covered that way, perhaps they haven't been considered to be basic. I bet if there are enough requests the project would improve the documentation in those areas.

anyone here around when msdn would send out 70+ cdroms only to replace them 3 or 6 months later?

Yeah! I loved getting those MSDN discs in the mail and seeing what was new.

I have to say I miss the old VS6 MSDN days. It was so much simpler then with just a bunch of help files.

It is crazy that today documentation is still such a weak point. I just want clean documentation that I can format how I want (user style sheets) with lots of solid example code.

Yes! You'd buy visual studio, it would come on 6 CDs but only 2 of them were VS. The rest was MSDN docs.

My big problem reading Microsoft docs is the pattern (around Visual Basic docs?) where they put objects, properties, methods, functions, etc. in separate sections, making it hard to figure out what applies where. Are they planning to address the difficulty of getting information out of the structure at all, or are they just putting window dressing on it?

[PM on the docs.microsoft.com team]

Yes, we are planning to address content structure to make sure that all important reference and conceptual information is well-organized and accessible. If you have any particular concerns regarding this, feel free to shoot me an email: dendeli [at] microsoft

I have somewhat of an interest in UWP. I'm not actively pursuing it but everyone once in a while I take a look to see if something worth my time is going on.

Now the best method I've found for finding content on msdn is a google search. If this no longer works my UWP interest will probably not be worth the bother.

An interesting thing here is the source repositories. Sources are Markdown + YAML frontmatter, as many of the static generators use nowadays, but particularly given the source repositories are hosted on GitHub it's hard not to notice the Jekyll similarities.

Nice to see MSDN move to more modern design. But I don't see any search capability?

Shameless pug, We currently working on documentation hub for developers https://www.docsapp.io/

As someone searching for an enterprise grade replacement to our current system of using MS word -> pdf -> CD to publish and maintain 500+ user and install guides...

-what flavor of Markdown do you support (captions/TOC/auto-number figures and tables)

-can I paste images from the clipboard directly into the editor (like one can with github issues)?

-what's the advantages over setting up my own git repo and using something like gitbooks?

....

You _really_ should have a demo available for people to try out.

Here is link to demo published site https://demo.docsapp.io/

- We support Github Flavored Markdown

- We dont have paste image from clipboard, but we will add the feature idea to roadmap.

- We provide support for versioning, fulltext search, private internal documentation (soon)

Yeah, a lot of Microsoft's Enterprise customers are also stuck with archaic software and deployment systems, both built following Microsoft's advice to use ASP.NET WebForms and Entity Framework for everything.

It would be a nice start if the farce of searching for some obscure error, finding an even more obscure forum entry linking to some MSDN page, navigating to this page just to see that it does no longer exists.

Are they going to fix the page load times? MSDN is terrible for click-wait-scroll usage, especially if you're trying to use the left navigation drilldown.

From the article:

> Fundamentals like site performance are a key feature and something many customers have asked us to improve on UserVoice. Page load time on docs.microsoft.com are between 50-300% faster in terms of load time and we are better geo-distributed than ever before. We’ve also built on an architecture that is running 100% on Azure.

I wasn't sure if it was just an issue of my browser, plugins, or the site was just agonizingly slow. Apparently it was the latter.

So, will I have to login into something to read the docs now?

Not from I've seen, but you can login with a variety of accounts to comment.

Yikes. Seems that almost no one designing websites bothers to study the more important parts of typography. Recently, typography has been bastardized to mean "an expensive looking sans serif font."

But there is really important knowledge out there regarding ease of reading, contrast, ideal formatting, etc.

Cant believe that they choose a font weight that is so light. That alone makes this redesign way worse than the original.

The blog portion uses a light font. The documentation part doesn't.

Well I jumped the gun then. I just assumed they would use the chance to show off their new format with a post about their new format. Guess not.

Looking at the actual documentation site, its not bad on first glance.

reminds me docs.google.com

I thought it as a canonical pointer for Office 365 docs.

now all their links are going to be broken, then they'll change everything again in 2years. typical ms.

[PM on the docs.microsoft.com team]

Not at all. We do graceful 301 redirects, so for all content from MSDN/TechNet that gets moved, none of the references will break.

yes we live pastels and hipster fonts.

We've asked you before to stop posting uncivil and/or unsubstantive comments to Hacker News. If you keep doing it, we'll ban your account, so it would be much better if you would stop doing it.

https://news.ycombinator.com/newsguidelines.html

https://news.ycombinator.com/newswelcome.html

Reply on news.ycombinator.com