Introducing docs.microsoft.com

https://docs.microsoft.com/teamblog/introducing-docs-microsoft-com/

by yread • 10 years ago

249 186 10 years ago

docs.microsoft.com

zx2c4• 10 years ago

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.

bobbles• 10 years ago

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

acqq2• 10 years ago

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.

Zekio3• 10 years ago

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

userbinator3• 10 years ago

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.

acqq2• 10 years ago

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)

csours2• 10 years ago

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

danfernandez4• 10 years ago

[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• 10 years ago

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

r00fus• 10 years ago

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

xcrunner529• 10 years ago

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.

Terretta• 10 years ago

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

sz4kerto2• 10 years ago

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.

cm33• 10 years ago

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.

keypress• 10 years ago

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

sz4kerto2• 10 years ago

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

jimjimjim• 10 years ago

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.

chiph• 10 years ago

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

lmm• 10 years ago

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.

pandler• 10 years ago

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.

simula67• 10 years ago

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.

PakG12• 10 years ago

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.

glaberficken2• 10 years ago

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.

tgb• 10 years ago

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.

cooper12• 10 years ago

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)

jakub_g2• 10 years ago

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

avuserow• 10 years ago

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.

insertnickname• 10 years ago

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

userbinator3• 10 years ago

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.

rl3• 10 years ago

I want 1998 back.

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

userbinator3• 10 years ago

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.

JorgeGT• 10 years ago

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.

taspeotis• 10 years ago

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

neppo• 10 years ago

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.

danfernandez4• 10 years ago

[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 :)

fredley• 10 years ago

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.

Zekio3• 10 years ago

Block livefyre.com javascript and they stop appearing

nailer3• 10 years ago

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.

nacs• 10 years ago

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.

sp3323• 10 years ago

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

txdv• 10 years ago

What monitor do you have?

flatline• 10 years ago

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.

jbb555• 10 years ago

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

piyush_soni4• 10 years ago

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?

sp3323• 10 years ago

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?

asquabventured• 10 years ago

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

RubyPinch• 10 years ago

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

abimaelmartell• 10 years ago

I really hate the popup thing.

Raphmedia2• 10 years ago

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

pinouchon2• 10 years ago

mixmastamyk• 10 years ago

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.

sixhobbits• 10 years ago

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.

dave20002• 10 years ago

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.

kevin_thibedeau• 10 years ago

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

deepakg• 10 years ago

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

jackvalentine• 10 years ago

Also, docs.com. A Microsoft product.

staticelf• 10 years ago

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

krylon2• 10 years ago

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• 10 years ago

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.

antod• 10 years ago

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.

dsfuoi• 10 years ago

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

Zekio3• 10 years ago

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

pjc50• 10 years ago

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• 10 years ago

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.

fibonachos• 10 years ago

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.

foota• 10 years ago

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

JonoW• 10 years ago

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

cmrx642• 10 years ago

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

realusername• 10 years ago

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

seanmcdirmid• 10 years ago

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

danfernandez4• 10 years 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!

jug• 10 years ago

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.

Szel• 10 years ago

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.

Jedd2• 10 years ago

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• 10 years ago

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• 10 years ago

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

tallanvor• 10 years ago

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.

Jedd2• 10 years ago

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.

tobyjsullivan• 10 years ago

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

I just assumed they meant Sharepoint there.

mvdwoord• 10 years ago

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• 10 years ago

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

...

koyote• 10 years ago

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.

pionar2• 10 years ago

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

runako• 10 years ago

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.

1wd• 10 years ago

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. :(

danfernandez4• 10 years 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!

Iv• 10 years ago

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.

pjmlp3• 10 years ago

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.

nailer3• 10 years ago

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

codecamper• 10 years ago

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

pionar2• 10 years ago

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

satysin• 10 years ago

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.

krautsourced• 10 years ago

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• 10 years ago

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

drglitch2• 10 years ago

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!

drglitch2• 10 years ago

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 :)

yread• 10 years ago

Well it looks quite horrible on desktop as well

WillKirkby• 10 years ago

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• 10 years ago

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• 10 years ago

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.

_pmf_• 10 years ago

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.

mikerichards• 10 years ago

yes we live pastels and hipster fonts.

dang• 10 years ago

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

sickbeard• 10 years ago

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

dend4• 10 years 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• 10 years ago

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

nathanaldensr• 10 years 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.

docsapp_io2• 10 years ago

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/

rubidium• 10 years ago

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_io2• 10 years ago

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)

forgotAgain• 10 years ago

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.

radicalbyte• 10 years ago

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.

vtlynch2• 10 years ago

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.

ygra4• 10 years ago

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

vtlynch2• 10 years ago

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.

qjighap• 10 years ago

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.

WorldMaker3• 10 years ago

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.

swills• 10 years ago

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

csours2• 10 years ago

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

projektfu• 10 years ago

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?

dend4• 10 years 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• 10 years ago

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.

dend4• 10 years ago

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

We are fixing that. Thank you for the feedback!

hobs• 10 years ago

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.

sosborn• 10 years ago

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

Navarajan• 10 years ago

reminds me docs.google.com

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

Introducing docs.microsoft.com

Related Stories