Hacker News Reader

Comment by edent | Hacker News Reader

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.

View on HN

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.

The thing is it shouldn't be that way in the first place isn't it? Take the golang spec, for example.

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 second is that this increases the distance between the web as specced and the [much much much] larger developer community, and things like <img srcset> / <picture> show the benefit of having less of a communications chasm between those groups.

That doesn’t mean that specs can’t be precise but simply that good technical writing can accommodate a wide audience.

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

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.

There is a tradeoff between simplicity/readability and "define how to handle all the edge cases".

Web specs recently have sacrificed the former to handle the latter, not least because past experience with web specs that sacrificed the latter to do the former was so horrible...

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

It's been years since I stopped contributing to and reading MDN, but this editorial stance seems to have disappeared, unfortunately.

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 readable. It's a great learning tool to get up to near-proficiency, and then the Reference is there for all those little "but I wonder what happens when..." questions.

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

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.

What even does "the list of methods" mean? Do you mean the builtins? Those are at the docs for built in functions.[1] Or do you mean the list of all functions? Because that doesn't exist for the very good reason that it doesn't make sense to have a list like that for python. There's the module index[2] though which lists every available module, linking to their docs which list all the available functions in those modules.

Having a single list of all functions in python makes very little sense for the simple reason that you'd not be able to find what you're looking for in that list so you might as well just use the search in the first place.

Side note: if there's a specific function you'd like to get the documentation for you can get that easily from the interactive python prompt with the "help" function:

    >>> help(zip)

And I fail to see the "missing examples". While it's true that most modules don't contain examples for every single function they usually contain a few examples for the overarching concept.

So which part exactly of the python docs is bad? IMO they are, by far, the best docs any programming language has.

[1] https://docs.python.org/3/library/functions.html [2] https://docs.python.org/3/py-modindex.html

Yes, I realize I can use help. Does it being available in one place mean that it shouldn't be available in others? If I'm in an IDE I don't always have the command prompt in front of me, and that should be fine!

So here's the standard library page for Python lists: https://docs.python.org/3/library/stdtypes.html#sequence-typ...

As a new python programmer, how am I supposed to know that the comprehensive API docs are actually in the tutorial? https://docs.python.org/3.1/tutorial/datastructures.html

Compare that to Javadocs (something Java got right!): https://docs.oracle.com/javase/8/docs/api/java/util/List.htm..., and .NET is similar. Ruby is also ok in this regard: https://ruby-doc.org/core-2.2.0/Array.html

(Javascript is a mess of course!)

As a "lowly CSS developer", I'm actually okay with this. w3.org specs are meant for browser developers, MDN docs (supposedly) are meant for web developers.

MDN resources are written for web developers (ie. consumers of the already implemented language spec). The W3 spec has to be written for its implementors and is necessarily much more complicated.

Reply on news.ycombinator.com