Hacker News Reader

Comment by kqr | Hacker News Reader

I think this is a cultural difference. Python documentation tends to be of the cookbook style, where you have long instructions surrounding specific examples. This works well for some people.

Other language communities (the typical example for me is Haskell) aim more for reference style documentation, emphasising lists of the possible operations and then trusting people to sequence those operations as they wish themselves. That's the type of documentation I like.

I have yet to find a language community that does a good job of both of these styles of documentation at the same time. C# is sometimes in the right direction, but not always.

View on HN

Neither Python's style nor Haskell's style is sufficient. Howtos ("cookbook" style) and reference information are completely inadequate on their own.

The only acceptable documentation is that which hits all four quadrants of the Divio documentation system[1]: tutorials, how-to guides, reference information, and conceptual explanations. Each of these kinds is necessary in a different situation.

If there's a "cultural" aspect, then it's only in which of the four kinds of docs that those two communities ignore.

[1] https://documentation.divio.com/

I'm not completely convinced that these four categories are The Categories – but the general idea is absolutely what I mean. Thanks for the reference!

I barely know it, but my brief experience with clojure has inspired me on how documentation should work.

Ex. https://clojuredocs.org/clojure.core/reduce

The pattern is definition -> description -> community examples.

If I ever invent a language I am copying this format.

That works for one-offs, but becomes a problem when you're working with a set of interrelated features, like a class. There, the very first thing I need is a high-level overview, not a reference. Of course, the reference is still useful for those who are familiar with the thing at hand.

Isn't that basically the PHP model? Which isn't to say it's bad, I remember it as quite exhaustive: https://www.php.net/manual/en/function.strptime.php

Perl modules often have a long prose introduction, some cookbook examples, followed by a reference style list of all the functions/methods/integration points. Usually pretty comprehensive, although you don't have to have good docs to be on CPAN.

R does a good job imo. Look at the vignette for print in R vs the help page in python. You get your reference style list of possible arguments, you get info on usage as well as additional examples, you even get a See Also section with further reading, and the whole thing has a citation you can reference. The entire language is documented thoroughly like this.

R is a good one indeed. I still haven't figured out how to get a good overview of the functions available in R grouped in some sensible way, but at least once I know which function I want it's often very well documented.

> I still haven't figured out how to get a good overview of the functions available in R

Is not obvious, but can be done from the inside with plain R.

You could also want to type install.packages('ctv') and take a look to Cran task views

Reply on news.ycombinator.com