
Introducing docs.microsoft.com - yread
https://docs.microsoft.com/teamblog/introducing-docs-microsoft-com/
======
zx2c4
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.

~~~
danfernandez
[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.

~~~
davidgerard
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.)

~~~
dend
[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.

~~~
prodigal_erik
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.

------
sz4kerto
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.

~~~
pandler
> 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.

~~~
glaberficken
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.

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

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

~~~
Someone
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.

~~~
zacmps
It's called meta-guiding

------
koyote
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.

~~~
pionar
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](https://msdn.microsoft.com/library)
[1]
[https://technet.microsoft.com/library/default.aspx](https://technet.microsoft.com/library/default.aspx)

~~~
runako
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.

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

------
hackbinary
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.

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

We are fixing that. Thank you for the feedback!

~~~
hobs
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.

------
Jedd
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?

~~~
mavhc
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.

~~~
rtpg
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

~~~
hvidgaard
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.

------
krautsourced
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.

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

------
qjighap
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.

------
drglitch
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!

~~~
drglitch
Replying to self: tables are completely broken on mobile too - eg
[https://docs.microsoft.com/en-us/multi-factor-
authentication...](https://docs.microsoft.com/en-us/multi-factor-
authentication/multi-factor-authentication-get-started-adfs-w2k12) and scroll
to 'options' \- it's about 5 CHARACTERS wide on iPhone 6 :)

~~~
yread
Well it looks quite horrible on desktop as well

------
Iv
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.

~~~
pjmlp
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.

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

~~~
pjmlp
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...](https://access.redhat.com/documentation/en-
US/Red_Hat_Enterprise_Linux/7/html/Developer_Guide/index.html)

~~~
oblio
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.

~~~
pjmlp
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.

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

~~~
jackvalentine
Also, docs.com. A Microsoft product.

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

~~~
nathanaldensr
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.

------
mvdwoord
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.

~~~
Medowar
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](https://github.com/Azure/azure-content.git)

Azure RMS? git clone [https://github.com/Microsoft/Azure-
RMSDocs.git](https://github.com/Microsoft/Azure-RMSDocs.git)

...

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

~~~
cmrx64
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...](https://docs.microsoft.com/teamblog/content/images/2016/05/DocumentationExample.png)

To one of mine: [https://imgur.com/rFwTqUW](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](https://imgur.com/YKvFxCh)

~~~
danfernandez
[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!

~~~
cmrx64
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.

------
WillKirkby
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;}

~~~
mediumdeviation
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.

~~~
ebrewste
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.

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

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

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

~~~
krylon
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.

~~~
vezycash
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.

~~~
krylon
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](http://www.postgresql.org/docs/9.4/static/index.html)

~~~
jrapdx3
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.

~~~
anarazel
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.

~~~
jrapdx3
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.

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

~~~
satysin
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.

------
projektfu
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?

~~~
dend
[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

------
forgotAgain
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.

------
WorldMaker
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.

------
docsapp_io
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/](https://www.docsapp.io/)

~~~
rubidium
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.

~~~
docsapp_io
Here is link to demo published site
[https://demo.docsapp.io/](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)

------
radicalbyte
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.

------
_pmf_
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.

------
pjc50
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.

~~~
dantiberian
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.

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

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

------
vtlynch
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.

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

~~~
vtlynch
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.

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

~~~
dend
[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.

------
Navarajan
reminds me docs.google.com

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

------
mikerichards
yes we live pastels and hipster fonts.

~~~
dang
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/newsguidelines.html)

[https://news.ycombinator.com/newswelcome.html](https://news.ycombinator.com/newswelcome.html)

