16 ms·
Introducing docs.microsoft.com
- mvdwoord 11y agoI 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 11y agoAll 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 ...
- koyote 11y agoI 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 11y agoDepending 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 11y agoYou 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 11y agoNot to mention search on MS sites essentially doesn't work (unless something has changed).
- 1wd 11y agoAgree. 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. :(
- danfernandez 11y ago[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!
- zx2c4 11y agoFrom 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.
- bobbles 11y agoIt would be nice to have a long form option, especially when intending to CTRL+F the page
- acqq 11y agoTheir 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.
- userbinator 11y agocan 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.
- sz4kerto 11y agoOh 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.
- cm3 11y agoIf 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.
- keypress 11y agoIf it weren't for tabs, a window resize could help there.
- sz4kerto 11y agoThere are other stuff you can store on the left/right sides, especially when it's a documentation site. Typically a nice hierarchical ToC.
- jimjimjim 11y agoI'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.
- wastedhours 11y agoI'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).
- 11y ago
- deepakg 11y agoInteresting choice of domain name. Coming from docs.google.com, I almost thought this was Office 365.
- jackvalentine 11y agoAlso, docs.com. A Microsoft product.
- staticelf 11y agoNice, I've always found msdn to be a bit hard to navigate through.
- krylon 11y agoYes! 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 11y agoTheir 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 11y agoIt'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
- dsfuoi 11y agoSo, will I have to login into something to read the docs now?
- Zekio 11y agoNot from I've seen, but you can login with a variety of accounts to comment.
- pjc50 11y agoAre 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 11y agoFrom 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.
- fibonachos 11y agoI 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.
- foota 11y agoMaybe I'm just losing my eyesight, but does anyone else find that font impossible to read?
- JonoW 11y agoThey have a toggle for light/dark themes (dropdown in the right hand col) if it helps?
- cmrx64 11y agoI 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/DocumentationExample.png https://docs.microsoft.com/teamblog/content/images/2016/05/D... 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
- realusername 11y agoMine looks similar to yours but even a bit lighter than your screenshot, it's really totaly unredable even when selecting the text.
- seanmcdirmid 11y agoIt looks like they are using segoe UI Light with a bad contrast (background too white, text too dark). Their visual design needs work.
- danfernandez 11y ago[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 11y agoAwesome! 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.
- Jedd 11y agoAt $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 11y agoSituation: 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.
- alblue 11y agoObligatory XKCD reference for above: https://xkcd.com/927/ https://xkcd.com/927/
- rtpg 11y agoSolution: 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 11y agoYou 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.
- brazzledazzle 11y ago
- Iv 11y agoI 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 11y agoJust 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 11y agoredhat.com/docs and (back when Sun was a thing) docs.sun.com were great.
- pjmlp 11y agoWhere 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_Enterprise_Linux/7/html/Developer_Guide/index.html https://access.redhat.com/documentation/en-US/Red_Hat_Enterp...
- oblio 11y agoI'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 11y agoIf 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.
- codecamper 11y agoanyone here around when msdn would send out 70+ cdroms only to replace them 3 or 6 months later?
- pionar 11y agoYes! You'd buy visual studio, it would come on 6 CDs but only 2 of them were VS. The rest was MSDN docs.
- satysin 11y agoYeah! 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.
- krautsourced 11y agoUgh. 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 11y agoAgree, it's so irritating that I stopped reading the article and came back to hacker news to read the comments..
- deleted 11y ago[deleted]
- deleted 11y ago[deleted]
- drglitch 11y agoLivefyre 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 11y agoReplying to self: tables are completely broken on mobile too - eg https://docs.microsoft.com/en-us/multi-factor-authentication/multi-factor-authentication-get-started-adfs-w2k12 https://docs.microsoft.com/en-us/multi-factor-authentication... and scroll to 'options' - it's about 5 CHARACTERS wide on iPhone 6 :)
- yread 11y agoWell it looks quite horrible on desktop as well
- WillKirkby 11y agoSome 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 11y agoAre 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 11y agoNot 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.
- _pmf_ 11y agoIt 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.
- mikerichards 11y agoyes we live pastels and hipster fonts.
- dang 11y agoWe'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
- sickbeard 11y agonow all their links are going to be broken, then they'll change everything again in 2years. typical ms.
- dend 11y ago[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.
- dep_b 11y agoI thought Microsoft Open Sourced their docs to Stack Overflow a long time ago?
- nathanaldensr 11y agoHard 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.
- docsapp_io 11y agoNice 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 11y agoAs 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 11y agoHere 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)
- forgotAgain 11y agoI 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.
- radicalbyte 11y agoYeah, 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.
- vtlynch 11y agoYikes. 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 11y agoThe blog portion uses a light font. The documentation part doesn't.
- vtlynch 11y agoWell 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.
- qjighap 11y agoI 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.
- WorldMaker 11y agoAn 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.
- swills 11y agoI like how they're boasting about how much effort it took them to figure out people want something simple and easy to use.
- csours 11y agoMore like one person or group spent a lot of effort on convincing their boss that people wanted this.
- projektfu 11y agoMy 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 11y ago[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
- hackbinary 11y agoI 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 11y ago[Disclosure: working on the team that built docs.microsoft.com] We are fixing that. Thank you for the feedback!
- hobs 11y agoThank 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.
- sosborn 11y agoThe real reason I shop on Amazon? Every other website spams those damn surveys when all I want to do is browse products.
- techsociety 11y agosoo, the same thing as google docs but you have to pay for it..
- dend 11y agoNot at all. docs.microsoft.com is the documentation portal and has nothing to do with the online Office Word service.
- Navarajan 11y agoreminds me docs.google.com I thought it as a canonical pointer for Office 365 docs.