News for hackers. Stuff that matters.
Re:Introducing docs.microsoft.com by zx2c4 on Wednesday May 04, 2016 @04:30AM (#11627000)
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.

Re:Introducing docs.microsoft.com by userbinator on Wednesday May 04, 2016 @06:41AM (#11627399)
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.

Re:Introducing docs.microsoft.com by acqq on Wednesday May 04, 2016 @08:04AM (#11627714)
> 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)

Re:Introducing docs.microsoft.com by danfernandez on Wednesday May 04, 2016 @04:27PM (#11631483)
[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.

Re:Introducing docs.microsoft.com by davidgerard on Wednesday May 04, 2016 @05:05PM (#11631796)
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.)

Re:Introducing docs.microsoft.com by dend on Wednesday May 04, 2016 @05:39PM (#11632111)
[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.

Re:Introducing docs.microsoft.com by prodigal_erik on Wednesday May 04, 2016 @06:34PM (#11632492)
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.
Re:Introducing docs.microsoft.com by xcrunner529 on Thursday May 05, 2016 @12:29PM (#11637514)
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.

Re:Introducing docs.microsoft.com by r00fus on Wednesday May 04, 2016 @06:57PM (#11632644)
> 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...

Re:Introducing docs.microsoft.com by acqq on Wednesday May 04, 2016 @04:57AM (#11627093)
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.

Re:Introducing docs.microsoft.com by Zekio on Wednesday May 04, 2016 @10:02AM (#11628402)
Not to mention, it makes it harder using Ctrl + F to find information.
Re:Introducing docs.microsoft.com by dmarlow on Wednesday May 04, 2016 @01:23PM (#11629915)
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.
Re:Introducing docs.microsoft.com by bobbles on Wednesday May 04, 2016 @04:37AM (#11627019)
It would be nice to have a long form option, especially when intending to CTRL+F the page
Re:Introducing docs.microsoft.com by csours on Wednesday May 04, 2016 @03:17PM (#11630926)
It makes it much easier to collect metrics on what people have read.
Re:Introducing docs.microsoft.com by Terretta on Wednesday May 04, 2016 @08:31PM (#11633098)
Agreed, this change seems like a step backwards. Docs aren't about page views.