Documenting the Web together • Hacker News Board

Re: Documenting the Web together

#201

Post by bfred_it » Fri, Oct 20, 2017, 9:13 AM UTC

frik wrote: post #166

ChuckMcM wrote: post #147

Guess they are going to band together to dethrone W3Schools :-) (only half kidding, that web site has has some serious staying power.) Related, when I was active in standards work (I learned just how badly that stuff was run) I discovered that new people in a standards group that was being formed would be lobbying to be the group Chairperson or Vice Chair. But the people who had been in standards bodies before were a…

W3School is very good to quickly look something up - short and always with a simple example. MDN is very good for details and in general as reference.

Short and always with a terrible example. I would never trust W3Schools with the simplest stuff. Take this form documentation, they don't even mention using

https://www.w3schools.com/html/html_forms.asp

Sadly, "html forms" brings up 3+ W3Schools pages of at the top.

Re: Documenting the Web together

#202

Post by anowlcalledjosh » Fri, Oct 20, 2017, 9:57 AM UTC

matt4077 wrote: post #160

ghostly_s wrote: post #143

Earlier quoted context omitted.

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…

I think Python is the worst-documented large language I use. For ```list``` it says: Lists implement all of the common and mutable sequence operations. Lists also provide the following additional method: ...where "common" and "mutable" are links. Meaning: the methods of lists are strewn across three different location, four if you count the constructors above this sentence.

Some context: the page documenting lists [0] is the same page that documents all* Python's built-in types; lists are documented in section 4.6.4, where section 4.6 is titled "Sequence Types — list, tuple, range".

Many operations on a list are much the same as the methods on a tuple, so they are documented in one place – section 4.6.1 "Common Sequence Operations" – rather than duplicated in both the list and tuple documentation. Similarly, many of the methods supported by list are also supported by bytearray, so they are documented in 4.6.3 "Mutable Sequence Types" rather than duplicated. To get from the section on lists to the two sections describing the available methods involves pressing page-up twice. Hardly "strewn across three different location", and there's always help(list) if you really want a list of every supported method.

*all the ones you'll use regularly, at least

[0]: https://docs.python.org/3/library/stdtypes.html#lists

Re: Documenting the Web together

#203

Post by myfonj » Fri, Oct 20, 2017, 10:32 AM UTC

fyrstenberg wrote: post #180

oevi wrote: post #176

Earlier quoted context omitted.

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 the…

Yup, that site seems to be basically redirector to Google redirector [1].

You can get the very same effect like DuckDuckGo keyword search but with "just the last redirect" with vanilla browser bookmark [2] with `%s` interpolation:

    https://www.google.com/search?btnI&q=%s%20site%3Adeveloper.mozilla.org

[1] https://github.com/lazd/mdn.io [2] https://www-archive.mozilla.org/docs/end-user/keywords.html - old page about feature in Firefox (currently the same works in Google Chrome as well). Amusing that the this `btnI` search is in the second example there.

Re: Documenting the Web together

#204

Post by dx034 » Fri, Oct 20, 2017, 10:50 AM UTC

nashashmi wrote: post #190

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…

Visual studio is not the only tool that went online. Many MS office products went this route. AutoCAD did too. However, AC has an option to download offline help. The office products have an option to stay offline. It does not work that well, in my experience. I guess some guy at MS thought: People look online for solutions; We should do that too! They broke things because the web browser was slow and the search resu…

The help function in Excel has been so useless and disruptive to work over more than a decade that I know many people (Excel power users) who just removed the F1 key. It got slightly better with Office 2016 but is nowhere nearly as productive as just googling your problem.

Re: Documenting the Web together

#205

Post by codedokode » Fri, Oct 20, 2017, 1:22 PM UTC

styfle wrote: post #196

ubernostrum wrote: post #101

Earlier quoted context omitted.

MDN already has compatibility tables for lots of things; if they're missing from a particular article, it's not because they're unsupported, it's because nobody has done the research and filled in the information (it's a wiki! You can add things!).

MDN didn't do a good job of advertising itself as a wiki. It wasn't until recently that you could login with a GitHub account. When you google "can i use flexbox", caniuse.com comes up but MDN does not. The other thing missing from MDN, is that caniuse.com shows browser support as a percentage. Now I know I'm safe to use flexbox since its supported by 97.74% of browsers in the wild. When a new feature comes out, I ad…

I don't like that caniuse by default shows only several recent browser versions, deceiving developers and making it look like some new technology is supported everywhere. It is clearly a "dark" UI pattern that motivates developers to make sites viewable only on latest Macbook.

Instead, it should show the year since which some feature is supported.

For example, for flexbox it could write:

IE - never

Edge - since 2015

Firefox - since Mar 2014

Safari - since Oct 2013

Opera - since Nov 2012

etc.

This gives a better picture.

Re: Documenting the Web together

#206

Post by lorenzhs » Fri, Oct 20, 2017, 2:30 PM UTC

ConfucianNardin wrote: post #187

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…

VS2017 opens the correct documentation most of the time, and in the default web browser. For C++, cppreference provides archives of all their docs: http://en.cppreference.com/w/Cppreference:Archives . Of course, that won't help you for Win32 or .NET. There's also https://zealdocs.org/

There's also https://github.com/jeaye/stdman which provides the pages from cppreference as manpages, and https://github.com/aitjcize/cppman (which I haven't used, but seems to look a bit nicer)

Re: Documenting the Web together

#207

Post by dmix » Fri, Oct 20, 2017, 2:43 PM UTC

vbezhenar wrote: post #127

edent wrote: post #77

We were speaking about this at the W3C's Advisory Board meeting in London earlier this week. It distresses me that the specs on w3.org are so hard to read for the average developer. It's great to see how MDN focuses on simplicity, readability, and usable examples.

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.

These specs are still designing systems that will be used by humans. If they can't be communicated effectively by the designers then it's likely they are too complicated themselves.

It would be a good exercise to require the public documentation parsable by humans. At least when it gets beyond the proposal stage.

Re: Documenting the Web together

#208

Post by thanatropism » Fri, Oct 20, 2017, 5:53 PM UTC

vxNsr wrote: post #199

thanatropism wrote: post #115

Earlier quoted context omitted.

What makes it a vanity domain? Just imagine how much printed material has circulated since the 90s with the mdn.com address. Why do you want to break the web?

It's a vanity url because it's small and can be used by tons of different orgs. Not sure why we're suddenly so sad about losing some tiny corner of the web that is very unlikely to have a huge effect irl. I used to bookmark things judiciously 7-8 years ago, that bookmarks list is completely useless today because >90% of the links are dead, that's okay though, it's the way things go. Happens with real-world objects to…

But people use it. You seem to think that being a web technologist gives you eminent domain over the web.

Re: Documenting the Web together

#209

Post by shpx » Sat, Oct 21, 2017, 2:41 AM UTC

Freak_NL wrote: post #200

oevi wrote: post #176

Earlier quoted context omitted.

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

If you set up your browser's default search engine as DuckDuckGo, this works from the location bar (at least in Firefox): !mdn await This will perform a query to DuckDuckGo (the non-tracking search engine) first, and automatically redirect to MDN. No need for extra add-ons; this is one of the standard set of 'bangs' DuckDuckGo provides.

If you go to chrome settings -> Manage search engines and define a new search engine with Keyword: "m" and "URL with %s in place of query": https://www.google.com/search?&q=site%3Adeveloper.mozilla.or... typing "m await" in the omnibar will jump to the first google result from MDN, which is what it seems mdn.io does.

https://news.ycombinator.com/item?id=15306429 is my list of custom search engines.

Re: Documenting the Web together

#210

Post by CoryG89 » Sun, Oct 22, 2017, 12:21 AM UTC

1k2ka wrote: post #148

CoryG89 wrote: post #136

Earlier quoted context omitted.

While we're on MDN related awesomeness, shameless plug: Back when I was in school, I made this Chrome extension which allows you to jump directly from the address bar to the MDN page you want: https://chrome.google.com/webstore/detail/mdnjump/mfjekjhknp...

If you use DuckDuckGo as your standard search engine you can also prepend "!mdn" to your search query to search MDN. This also works with any website wich supports search I think. Other good ones include "!hoogle", "!hn", "!yt", "!g", and the list goes on.

This will bring you to a search result page, yes? My ext combines Google's I'm Feeling Lucky to jump straight to the page for the top result, which I find works 99% of the time I'm looking for something on MDN.