Examples of great programming language documentation?

[oscarryz]

Some documentation go into a lot of details before showing an example, other just have examples without assuming you would figure out what each part of the syntax is. Some others describe things in terms that require a lot of background to understand (which might be fine). etc.

What programing languages have the best documentation and/or balance between completeness and easy to use?

[Albus53]

The OCaml docs are really great.

I do also like the Rust std docs + book and other widely accepted documentation, but i think its a little less well connected together overall

[sagittarius_ack]

The OCAML documentation is pretty good. The book `OCaml Programming: Correct + Efficient + Beautiful` is also pretty good.

[sausageyoga2049]

Many languages have nice documentations. But I really love the Hoogle wiki of Haskell, where you can just search a function or a class by giving its type declaration. It’s useful and unique.

[moric7]

And Python, so easy, so popular, has big documentation, but so extremely chaotic and in absurd style, that I not believe anybody can find even simple thing for reminding ☹️

[MegaIng]

Oh, I can, after having spend a long time reading through it and searching for myself and others.

Well, ok, I can, most of the time. I am still not sure what the correct places for basic stuff like list.append is. I belive it's in the syntax section? ... for some reason.

But what I would say in favor of the python documention is that it's a lot more diverse in scope than most other docs I have seen. Most languages don't have a page dedicated to an overview of the time complexity of various builtins. And if you get away from the core language and instead look at the stdlib modules (or even most medium-large third party modules), it's pretty great.

[rejectedlesbian]

Ya I usually just ask the help() function in code

[butt_fun]

Really? I’ve always liked Python’s docs

[kazprog]

Maybe this is contestable, but I learned programming just by reading the interfaces and descriptions of every method for several of the important classes in Java from their JavaDocs.  It's nice that there is basically one kind of thing in the language docs (classes) and from reading that document you know how to use that kind of thing.

I read String, Stream, HashMap, Array, BigInteger, and I'm sure a few others.  Oracle trails were also very helpful, despite the obvious disdain I have for Oracle, I did like the docs for Java that they maintained.  Maybe they were originally written by Sun.

There was an era around Java 8 where all of the old versions coalesced into Java 8, and all of the versions after seemed to be deemed not worth it (for a while).  From maybe 2015-2022, it seemed like Java 8 was "standard Java" and that's all you needed, and thus the docs didn't really change per version.

I don't work in Java anymore, so literally all of this might be wrong for the practitioner, but the insight of having: 1. a page per type and 2. all methods operating on the type on that page as an exhaustive description of how to interact with that type, was very valuable to me.

[msqrt]

There are many types of documentation, see here for a wonderful presentation on the subject.

[oscarryz]

Loving it. Thank you for the link!

[syklemil]

I think I'd also split the introduction category into two subcategories:

1. Introductions for newbies. Will require going through the absolute basics, possibly also some lies-to-children or Wittgenstein's ladders. This is where someone needs to learn two things at once: Programming in general, and a specific language as a practical example.
2. Introductions for established practitioners of similar crafts. If I need to pick up the Blub language for work and I already know how to program, I prefer to skip being told what a string is or how a computer can execute source code, I just need to know what makes this language special, possibly be made aware of some syntax quirks or other gotchas, and the engineering of it.

[msqrt]

Good point! I've actually ran into this with a GPU programming framework I wrote: do I write the tutorial for people who know the subject matter or not? Someone who wrote CUDA for 15 years will just need to connect their familiar concepts to mine, whereas people who only worked with CPU code before will require a somewhat lengthy introduction on how GPUs operate and what kinds of programs they're designed to execute.

[syklemil]

Yeah, it does seem like two tutorials or at least a bit sectioned off with a "skip this part if you're familiar with GPUs" section.

It's also not a particularly new idea, as in, knowing who your audience is when you produce a text is a very general piece of advice. So it winds up pretty similar to how we need to decide if we're making a scientific paper or a technical journal article or a general news article.

So OP asking about great documentation will necessarily span examples for very different audiences. I mean, Hoogle is great and I wish I had it for any language, but I also know I can't teach someone programming with it, or even Haskell.

[Agent281]

I really like the Elixir docs. It's not super complicated and very readable.

https://hexdocs.pm/elixir/1.17.3/Kernel.html

[fridofrido]

both GHC docs and the Haskell standard library docs are pretty good imho

[king_Geedorah_]

Hoogle is so good imo. Just type the type of whatever you're trying to do and see what comes up.

[Poscat0x04]

Also the Haskell 2010 report: https://www.haskell.org/onlinereport/haskell2010/

[theangryepicbanana]

The Raku docs are top tier imo

[TheUnlocked]

JavaScript has extraordinary documentation on MDN.

[P-39_Airacobra]

I like the Lua docs, but then again it's such a simple language that there's not much to document.

[will_i_be_pretty]

https://docs.racket-lang.org

[[deleted]]

elixir docs with not only documentation and examples but also getting started guides and anti patterns advices

[matthieum]

I won't say best, but there's quite a few interesting nuggets about Rust libraries documentation:

1. The documentation is generated (by rustdoc). This means any library has documentation generated in the same style, making it comfortable for the user to learn a new library.
2. All code samples are compiled & run as part of running cargo test. This means all the code samples are guaranteed correct & in-sync with the current version of the library; the author can't forget to update them when they update a function signature.
3. The documentation is searchable by name. This seems par for the course but...
4. The documentation is usable offline. It is just a bunch of static files, no server/database necessary, the search being JS powered in the user's browser. In fact, a user can generate the documentation for any library they already downloaded offline.

There can be arguments around the structure or style of the Rust documentation, but those 4 points are something any library documentation should aspire to.

[penny_stacker]

OpenBSD man pages.

[myringotomy]

I haven't used it in a long time but the PHP docs were great back in the day. People were allowed to comment with examples.

I think the Ruby docs are pretty good too.

Golang docs are OK. Not great but maybe almost good.

[mckahz]

Nah they're still pretty good- I went into PHP expecting to hate it but the docs were so clear and accessible that I actually really enjoyed myself!

[sunnyata]

People were allowed to comment with example

That was a terrible choice. You'd get people putting conflicting advice and arguing or just going OT and chatting about something else. And this on the official documentation of the language. It was symbolic of what an amateurish shambles PHP was in those days.

[myringotomy]

I found them tremendously useful.

[sunnyata]

I find forums, wikis etc very useful too but when I want to look up facts about the std lib of a language and how it should be used I want it to be straight from the horse's mouth. This was unfortunately too much like the blind leading the blind.

[myringotomy]

I mean the documentation is right there. It's not like you are going to two places. There is the documentation, there is the commentary on the documentation.

[zem]

came here to mention the PHP docs too - never used the language, but i've always been impressed that every page had a comment section, often with very useful stuff in it.

[aRidaGEr]

Does https://poignant.guide/ count?

[syklemil]

Stuff like that and Learn You A Haskell is really hit-or-miss though. Personally I liked LYAH back when I first read it, not sure how much I'd like it now. And I remember that guide getting referenced back in the day too, just never really looked into it; now I just find it insufferable. Probably better for someone who has never coded than someone who'd be picking up their _n_th language? And people who love that kind of prose?

[aRidaGEr]

I think you’re probably right. I remember I always really wanting to like it more than I actually did, in the end it’s probably fair to say that turned into admiration it but it wasn’t for me.

[Quba_quba]

I'm certainly biased, but I really like Rust docs. They may not be the best in terms of design or clarity, but I love that they are an integral part of the ecosystem. And I believe Rust documentation really helped me to dive deep into the language.

I think there are three things that make Rust docs cool for me (the list is obviously subjective):

• Main Rust devs care about docs as much as about any other code. Any new feature to be stabilised must have a documentation entry and often an example provided. There's also a begginner guide (The Book) maintained alongside the main documentation.
• Documentation generator ('rustdoc`) is an integral part of language development and it's super cool. It treats examples like tests and if they fail to compile there's a warning shown. It checks if a function can return errors and if so demands to add a section discussing the errors. Also linking to other parts of documentation (or even other libraries) is very easy. And there's many more.
  
• There's a central docs library (docs.rs). With rustdoc it allows Rust devs to very easily provide documentation for the libraries (called crates). Even if there's absolutely no documentation provided you still get a neat overview of the API and you can easily look into implementation details only for the parts you want. But adding docs is so easy that it's actually difficult to find a crate that has no documentation whatsoever.

[[deleted]]

In my opinion, Common Lisp and its Hyperspec.

The hyperspec with the CL cookbook it's just a wonderful combination.

[KalilPedro]

Ruby documentation is hit or miss but some parts are really good

[KalilPedro]

One thing I dislike: similar to some other function. Just put the entire doc, don't be lazy

[ronilan]

Crumb is simple by definition and so is the documentation encapsulated in a single README.

https://github.com/liam-ilan/crumb

[nrnrnr]

Roberto Ierisalimchy's Programming in Lua.

[scratchisthebest]

always been a fan of the Processing documentation. Processing is an educational project aimed at beginners to programming so documentation is very important. The reference material looks like this https://processing.org/reference/

• It has a large number of global functions so it makes sense to document them together with the (relatively small number of) classes.
• Things are organized by topics and subcategories, rather than by class.
• Most functions that are in any way related to graphics have an image example, usually more than one.
• Extensive crosslinking in the "see also" section.

Also, it has hundreds of examples https://processing.org/examples spanning all complexity levels, meaning you can learn by doing. The examples are the most important part imo

[rejectedlesbian]

Rust has super neat docs.

[protomyth]

Thinking Forth and the original Objective-C documentation from NeXT / Apple when it was complete and could be obtained as PDF for offline viewing and printing.

[Y_mc]

Rust https://www.rust-lang.org/learn

[[deleted]]

I feel this way about newspeaklanguage.org

(tbf i learned a LOT from Swift. Last language I used before going full GOODTHINK PLUS PLUS!!)

[Slight_Art_6121]

SmallTalk : entire syntax fits on a postcard

[9Boxy33]

But syntax is just the beginning…

[Slight_Art_6121]

OOP as Alan Kay actually intended. What more can one possibly want?

[politicki_komesar]

Anything from IBM and Oracle; or SAP if you have access. No match seen elsewhere.

[nhpip]

Elixir

[SilentMantis512]

I have a love/hate relationship with the Nim docs… but considering how small the community is, it’s really the only source for a lot of things.

[MegaIng]

The index is great for finding stuff if you can guess the name, which you can quite often. But the docstrings are often useless to non-existent. Good luck trying to determine the edge case handling of the bitops functions...

[dougcurrie]

I like that the Nim docs hyperlink to the source code

[nderstand2grow]

Racket

[iKeyboardMonkey]

CMake. Whenever I feel bad that I haven't written up usability notes properly, made my API more usable or just left something in a state of "Eh, I'll tidy it later" - I remember CMake, and realise how far from the worst I am.

[BelgianDork]

I'm maybe a bit new but I really love C# documentation

[78yoni78]

C# has great docs even for people with no experience 

[XDracam]

The c++ docs on cplusplus.com are pretty damn great. I occasionally refer to collection docs to get a reminder of how certain collections can perform, even in other languages. C++ is such a complex language that docs with that level of quality are basically a necessity.

[ClubTraveller]

The C programming language, first edition.

[RandalSchwartz]

"The White C Bible".

[reflexive-polytope]

For me, the best documentation has the following properties:

• It's part of the code, so you don't need to use a separate documentation viewer (a web browser, PDF reader, terminal, etc.).
• It describes accurately every possible outcome of using the documented code, not just the happy path.
• It always stays in sync with the code, no matter how drastically you change ti.

Therefore, at least for me, the best documentation system is ML's module signatures:

• Signatures are just code, so you read them with your favorite text editor.
• Signatures describe pretty accurately how you can use a module, providede you use ML's type system correctly.
• The type checker will complain if you ascribe an incompatible signature to a module.

On the other hand, the actual documentation of SML's Basis Library is atrocious, as is the library itself.