4 ms·

In my experience all three you mentioned have their own excellent areas. MDN covers a vast range of subjects and knowledge levels but is most laborious to main

In my experience all three you mentioned have their own excellent areas. MDN covers a vast range of subjects and knowledge levels but is most laborious to maintain and I have seen some gaps due to that. Rust is also similar in those aspects, but has different "documentations" that don't fully interconnect to each other yet. Rustdoc's automatic nature is great to have a complete and working documentation, but also means that API documentations are often weaker than those of MDN as the documentation should be embedded into the source code. Python has the same issues and also inconsistencies due to the lack of language-wide automatic documentation system (Sphinx autodoc is close but still annoying). Cppreference (perhaps not intentionally) covers only higher knowledge levels and absolutely standard matters. It is of course very clear that you can't really use cppreference for learning C++ from scratch, but it is well written as long as you fit with those assumptions and its writing quality is comparable to MDN in my opinion.

db48x 2y ago
Why does embedding the documentation into the source code make it weaker? The author can put as much or as little effort into the documentation as they want either way.
- lifthrasiir 2y ago
  A documentation is written for particular audiences, not always but typically users. And a user-directed documentation is largely a hindrance for whoever is actually updating a source code adjacent to that documentation, because it acts like a boilerplate template. An embedded documentation does make the absence of documentation obvious and helps towards the completeness, but not without a compromise. Ideally it should then be reordered and further elaborated externally so that it can be maximally useful. Rust has a good documentation but the general lack of such manipulation makes it often hard to navigate. For example `Vec` [1] has a lot of inherent methods with two separate orderings, where one is alphabetical in the sidebar and another is the declaration order, but none of them are actually logical and will benefit from reordering in general. Of course Rust folks are aware of this issue and have put a lengthy introduction with most important methods for each category, but that's less flexible and prone to future updates. [1] https://doc.rust-lang.org/stable/std/vec/struct.Vec.html https://doc.rust-lang.org/stable/std/vec/struct.Vec.html
  - db48x 2y ago
    I’m not so sure that the order of methods matters very much in most cases. In Rust you can at least present them in any order you like, or you can use the module or trait documentation to explain how the order matters.
projektfu 2y ago
C++'s canonical reference is a very thick book. I figure there is a conflict of interest between the published version and presenting an equivalent online. It's worth noting there is no good C documentation in one place, either. Python dumped the book quickly and went online, but that was probably more for the publisher not being interested in releasing new versions every time something changed. It's also a little younger, but still appeared before the widespread use of broadband internet. I think Perl was probably the first one to make documentation a real first class citizen, with perhaps Emacs shining a light in that direction.

db48x 2y ago

Why does embedding the documentation into the source code make it weaker? The author can put as much or as little effort into the documentation as they want either way.

lifthrasiir 2y ago
A documentation is written for particular audiences, not always but typically users. And a user-directed documentation is largely a hindrance for whoever is actually updating a source code adjacent to that documentation, because it acts like a boilerplate template. An embedded documentation does make the absence of documentation obvious and helps towards the completeness, but not without a compromise. Ideally it should then be reordered and further elaborated externally so that it can be maximally useful. Rust has a good documentation but the general lack of such manipulation makes it often hard to navigate. For example `Vec` [1] has a lot of inherent methods with two separate orderings, where one is alphabetical in the sidebar and another is the declaration order, but none of them are actually logical and will benefit from reordering in general. Of course Rust folks are aware of this issue and have put a lengthy introduction with most important methods for each category, but that's less flexible and prone to future updates. [1] https://doc.rust-lang.org/stable/std/vec/struct.Vec.html https://doc.rust-lang.org/stable/std/vec/struct.Vec.html
- db48x 2y ago
  I’m not so sure that the order of methods matters very much in most cases. In Rust you can at least present them in any order you like, or you can use the module or trait documentation to explain how the order matters.

projektfu 2y ago

C++'s canonical reference is a very thick book. I figure there is a conflict of interest between the published version and presenting an equivalent online. It's worth noting there is no good C documentation in one place, either. Python dumped the book quickly and went online, but that was probably more for the publisher not being interested in releasing new versions every time something changed. It's also a little younger, but still appeared before the widespread use of broadband internet. I think Perl was probably the first one to make documentation a real first class citizen, with perhaps Emacs shining a light in that direction.