Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Documenting the Web together

blogs.windows.com

Post reply on HN
Print view View original

171–180 of 212 posts

Re: Documenting the Web together

#171

Post by jasonkester »

I really miss the old MSDN Library. The 5GB installable one you'd get as one of the 200 DVDs in that giant case they'd ship you with your MSDN subscription back in the day.

It was awesome. You could hit F1 and it would instantly pop up good, detailed, documentation for whatever method or keyword was under your cursor. In any of their developer products, so it worked as well in SQL Server Management Studio as in VS.NET. Every language, every technology, updated monthly via Automatic Updates on your dev box.

But they stopped shipping it in favor of "web help". That's the thing where you hit F1 and it spends several seconds opening a web browser (a custom one in a new tab in the IDE for some reason), then several more seconds opening a "meet the mouse" style page telling you how to use the code editor window (which it had helpfully detected was your context when asking for help).

So in one stroke, they switched from the worlds most awesome help system at your fingertips to "just go open Chrome and type your search into Google, since that will at least get you something relevant".

Today, they've improved that workflow by trying to ensure that something relevant exists on MDN, provided you're searching for web-related stuff.

We're still about 10 years back from the state-of-the-art in 2003.

Shame.

Re: Documenting the Web together

#172

Post by foxylion »

frik wrote: post #168
TazeTSchnitzel wrote: post #103

Déjà vu. Previously ( checks email …almost exactly 5 years ago?! Christ, it was a long time ago), the web powers that be announced they were going to collaborate on a new web docs wiki.[0] I don't think it went anywhere because, well, MDN already existed. I'm glad they finally just surrendered to MDN, even if it was many years late. [0] https://www.w3.org/2012/10/webplatform.html.en

"One of our guiding principles in developing Microsoft Edge is that end users should never have to worry about which sites work in which browsers. This philosophy—”the Web should just work for everyone“—led to our choice to target the “interoperable intersection” of web APIs in our browser engineering." Many sites already don't work correctly in Edge, IE11 nor Firefox - it's too late, these are minor browsers, used b…

It depends on the user base. Customers of the company I work for mostly use IE or Edge and only Chrome because we highly suggest it. Without decent IE/Edge support we would have less customers.

Re: Documenting the Web together

#173

Post by chadaustin »

jasonkester wrote: post #171

I really miss the old MSDN Library. The 5GB installable one you'd get as one of the 200 DVDs in that giant case they'd ship you with your MSDN subscription back in the day. It was awesome. You could hit F1 and it would instantly pop up good, detailed, documentation for whatever method or keyword was under your cursor. In any of their developer products, so it worked as well in SQL Server Management Studio as in VS.NE…

Yeah, the old installable MSDN Library was really great. I loved how they approached each topic with three types of documentation: tutorials, concept overviews, and types-and-functions references. I still have the CDs on my bookshelf because I can't bring myself to throw them away. :)

Microsoft was really good at developer documentation.

Apps like Dash and websites like devdocs.io come close to the same experience, at least.

Re: Documenting the Web together

#174

Post by ygra »

acdha wrote: post #152
vbezhenar wrote: post #127

Earlier quoted context omitted.

Specs are not meant to be read by average developer. Average developer should read books. Specs are meant to clarify moot points between different implementations. Spec is like legal document, they are hard to read, but they serve their purpose.

I think that’s a very narrow view and it’s far from universally true. While a lot of W3C specs are impenetrable there are many counter examples at the IETF which might not be introductory level but are certainly easier for a developer familiar with the topic to follow. I think this is actually fairly important for two reasons. The first is simply that unreadable specs are just as bug prone as unreadable code, but the…

I think it also largely depends on what the spec describes. XML for example is rather abstract and can be hard to follow, but SVG is quite easy to read and in my opinion much better than any 3rd-party explanation (primarily because it's complete and error-free).

Re: Documenting the Web together

#175

Post by nl »

ghostly_s wrote: post #143
carussell wrote: post #123

Earlier quoted context omitted.

When this article first appeared, I wrote a long comment here (now deleted) about how the content Mozilla inherited from Netscape DevEdge originally straddled the split by fully embracing that there were two different mindsets the audience might be coming in with, and simply creating two different sets of docs. There were the JavaScript Guide and the JavaScript Reference, for example, and they were pretty thoroughly…

Python's official docs do a good job with this approach too, I think. The Python Language Reference is relatively easy to read for a lay-man when that's necessary, and includes the formal logic of the spec in little call-out boxes -- but it's also accompanied by the Python Tutorial, which manages to cover nearly everything while making no attempt to get into every edge-case and obscure method, keeping it focused and…

Oh wow, I disagree with this quite strongly. I find they lack useful examples, and it's ridiculously hard to find even the list of methods.

Re: Documenting the Web together

#177

Post by skocznymroczny »

shmerl wrote: post #76

> One of our guiding principles in developing Microsoft Edge is that end users should never have to worry about which sites work in which browsers. This philosophy—”the Web should just work for everyone“—led to our choice to target the “interoperable intersection” of web APIs in our browser engineering. That's a good move by MS. In this context it's great to see them supporting open codecs, and for istance OGG contai…

MS only implements standards when they don't get to make one. They didn't want to implement WebGL in their browsers until Safari/Chrome/Firefox had it and they risked being behind.

Same thing here. "Web should just work for everyone" means "Oops, people are making Chrome-only websites, we need to catch up on web standards so we aren't left out". Meanwhile they'll boast how you need Edge to watch 4k Netflix.

Re: Documenting the Web together

#178

Post by skocznymroczny »

roblabla wrote: post #100
shmerl wrote: post #76

> One of our guiding principles in developing Microsoft Edge is that end users should never have to worry about which sites work in which browsers. This philosophy—”the Web should just work for everyone“—led to our choice to target the “interoperable intersection” of web APIs in our browser engineering. That's a good move by MS. In this context it's great to see them supporting open codecs, and for istance OGG contai…

Because video-games is still the one place where Mac and Linux are lagging behind, and they have DirectX to thank a lot for that.

In case of Linux, you forgot availability of drivers, cohesive user experience, stability and ergonomy rather than programmer designed interfaces.

Re: Documenting the Web together

#179

Post by sambf »

fyrstenberg wrote: post #30

Don't forget you can use https://devdocs.io/ too which also searches MDN and store offline. The two are a great pair.

I'm using it as my primary source of documentation since a couple of years. Never been disappointed, and it saves a lot of clicks.

Re: Documenting the Web together

#180

Post by fyrstenberg »

oevi wrote: post #176
fyrstenberg wrote: post #30

Don't forget you can use https://devdocs.io/ too which also searches MDN and store offline. The two are a great pair.

There is also mdn.io which can be used as shortcut in every browser like this (for a search for 'await'): http://mdn.io/await

It seems neat on the surface but it also seem to involve two redirects, first one to google.com (which is not obvious and personally not something I would like), and then to MDN. It would be cool if it linked directly to the page on MDN or showed the content directly within the page.

And the second time I clicked I was met with this message, not mdn.io's fault but nonetheless (i.e. "google police" - not sure what they mean with "unusual activity", there is hardly any at the moment - maybe not enough? :) or maybe I just got a busy vpn exit point): https://imgur.com/itn48dZ

Post reply on HN