5 ms·

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

by edent 9y ago

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.

mattacular 9y ago
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.
deleted 9y ago
[deleted]
bzbarsky 9y ago
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...
- carussell 9y ago
  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.
  - ghostly_s 9y ago
    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.
    - matt4077 9y ago
      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.
      - anowlcalledjosh 9y ago
        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 https://docs.python.org/3/library/stdtypes.html#lists
    - nl 9y ago
      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.
      - Doxin 9y ago
        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 https://docs.python.org/3/library/functions.html [2] https://docs.python.org/3/py-modindex.html https://docs.python.org/3/py-modindex.html
- tamonesto 9y ago
  x
vbezhenar 9y ago
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.
- nazri1 9y ago
  The thing is it shouldn't be that way in the first place isn't it? Take the golang spec, for example.
- acdha 9y ago
  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.
  - ygra 9y ago
    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).
- dmix 9y ago
  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.
madeofpalk 9y ago
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.

by edent 9y ago

mattacular 9y ago

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.

deleted 9y ago

[deleted]

bzbarsky 9y ago

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

carussell 9y ago
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.
- ghostly_s 9y ago
  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.
  - matt4077 9y ago
    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.
    - anowlcalledjosh 9y ago
      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 https://docs.python.org/3/library/stdtypes.html#lists
  - nl 9y ago
    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.
    - Doxin 9y ago
      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 https://docs.python.org/3/library/functions.html [2] https://docs.python.org/3/py-modindex.html https://docs.python.org/3/py-modindex.html
tamonesto 9y ago
x

vbezhenar 9y ago

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.

nazri1 9y ago
The thing is it shouldn't be that way in the first place isn't it? Take the golang spec, for example.
acdha 9y ago
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.
- ygra 9y ago
  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).
dmix 9y ago
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.

madeofpalk 9y ago

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.