Comment by moksly | Hacker News Reader

Comment by moksly | Hacker News Reader

If people are frequently asking the same question then your information and how you deliver it is lacking.

You can solve this by making a FAQ, or your can write better information.

Having recently moved from Python (where the documentation is amazing) to TypeScript/JavaScript (where the documentation is horrendous) this issue has never been clearer to me. The only Python library that I’ve ever had to go outside the documentation to understand has been pandas. I can’t think of a single TypeScript issue I’ve run into that hasn’t ended with me going through an infinite amount of web searching and wading through a gazillion useless suggestions.

It might just be me of course. I never really liked the Microsoft documentation pages either, so maybe I’m just an oddity that can only read Python styled documentation, but maybe not. I mean, why does the Express library have a “security FAQ” which seems like it should basically have been a simple part of the “start here” guide? I’m probably missing something, but reading the security FAQ left me with the feeling you would be an idiot not to use the helmet library with express (at least until you know enough to know when not to use it), and if that is so, then it really shouldn’t be a separate FAQ should it?

I know I went down a side track, but it’s really the most perfect real world example I have of why this article is exactly right.

It's odd but when I have to write something with Python, its documentation really is terrible. There's not even index of functions in particular module, I have to open it, then find that function with ctrl+f. E.g. https://docs.python.org/3/library/os.html

Compare to golang: https://pkg.go.dev/os it provides list of all functions in particular module which I can glance over quickly and find what needed.

That's small thing, but really makes me spend so much more time when I need to use Python for something. I guess that's not an issue for experienced developers who memorized all functions they need.

And I never had issues with JavaScript thanks to wonderful MDN.

Python's the main language I've used professionally (i.e. used most by a long shot) and I agree. I think it's just a newer style, newer languages and frameworks seem to have a more structured/hierarchical/indexed style like that IME.

Newer? If you look at Javadocs, they're highly structured, at least as much as — and arguably more so than — Go docs.

I think it has got more to do with culture and tradition. Each language seems to have its own documentation culture. Python seems to favor docs in which structure is interleaved with prose.

I find Go docs to be pretty hard to make sense of. Often times they don't explain very well how to use a package. And browsing around different aspects of a library carries a feeling of obscurity.

Ultimately, I think documentation should be split up into multiple categories, ala https://documentation.divio.com/

Java is a newer language though isn't it? The 90's wasn't so long ago... right guys?

... guys? :(

Python is about 4 years older than Java (based on "initial release" listed on Wikipedia), so the pattern still fits between those two languages.

The best example of being lost in docs is Python's re (regex). Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top. If I have a specific requirement or want the gory details, I can always scroll down.

> Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top.

This is called a synopsis, and lack of one is the single biggest mistake that documentation authors make. When I look across the landscape of programming languages, I see them rarely.

Perl documentation always has a synopsis because it's a big cultural expectation, and it almost always useful to get the user started, or to jog the memory. Man pages have it, too, but they tend to cram too much useless information instead of restricting to common cases and patterns.

The issue is that there are conflicting use cases — "I want to refresh myself on how `re` works" and "tell me what order the arguments for `re.match` go in". I think the second use case is most frequent, so an index and some basic examples should go first, but after that a more in-depth synopsis can be very helpful.

Isn't it more natural that the summary comes first, before the details?

I don't think most visits to documentation involve reading the summary; they're either looking for a specific detail (which they can find via the index) or for a common snippet that can be expressed in an example.

If I'm using `re` and I check the documentation 20 times over the course of the week, I'll probably read the summary on my first visit, and then on each of the 19 subsequent visits I'll be looking for granular function details or patterns that I can copy. I think it makes sense to put the most frequently-used stuff at the top. The summary will probably be denser and harder to skim than the examples anyway.

I suppose it really depends though. What you want is to get a bit of everything before the break, so that the user can see a couple intro sentences, a few examples, the index (ideally in a sidebar), and the beginning of the overview before they even have to scroll.

I tend to agree. Python's style of documentation was always hard to parse for me. In comparison I really liked the Ruby core documentation. Short description with common use case examples followed by a structured list of all implemented functions and a sidebar linking to all relevant interfaces/superclasses. E.g. the Hash class document : https://ruby-doc.org/core-3.0.3/Hash.html

Python documentation isn't as nice to read as that of go or rust, and at places a bit hand-wavy. But compared to javascript/typescript it's well structured and thorough. GP just wasn't setting the bar all that high.

Many consider MDN the gold standard when it comes to language documentation and they cover all the JS browser API. I find it much preferable to Python’s docs.

If you’re talking about TS or Node docs, I’ll agree they’re not on the same level as MDN.

I like to use Dash https://kapeli.com/dash, which makes browsing the standard library for Python really fast and smooth. One could argue that you shouldn't need a separate app for documentation, and you might be right, but it is a great experience.

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.

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

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

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!

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.

> That's small thing, but really makes me spend so much more time when I need to use Python for something. I guess that's not an issue for experienced developers who memorized all functions they need.

I've been programming in python for almost 15 years and I don't know all the functions/classes/attributes of any module in the standard library probably. What I do know is that if I'm on a vanilla python shell I can type `help(module)` and I'll get that list in the shell directly, and even `help(module.function)` will give me enough context most of the time that I won't need to go online either.

However, as my daily shell, I use IPython, on which I have smart autocomplete that inspects the modules for me by just typing `module.`, hit tab and BAM! All the things inside the module pop up before me to explore. Something looks about what I need? I add a ? at the end an press enter, so `module.function?` will show me the docstring, nicely formatted with the signture (the same thing the built-in `help()` does).

So the online docs, for python, rest on an entirely different level. But sure, coming from other languages it may be weird not having what you're used to. It's part of the languages culture.

    dir(module)

    help(module.fn)

I agree that python documentation can be clunky especially in comparison with other languages. When I learned python I had experience in bash and R. Man pages and R vignettes have certainly spoiled me. R has usage, details, several examples, even a see also section for further reading. The equivalent python help page for a command like print is a little bit over six lines in comparison.

My biggest grip with Python documentation is that it often leaves flags and options underdocumented.

> Having recently moved from Python (where the documentation is amazing)

Huh? Python's online documentation is horrible. In addition to what vbezhenar said, there are gems like this:

The arguments shown above are merely the most common ones, described below in Frequently Used Arguments (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the Popen constructor - most of the arguments to this function are passed through to that interface. (timeout, input, check, and capture_output are not.) [1]

"Largely the same"? What, am I supposed to divine the actually available parameters?

For built-in types, the docs are missing a way to quickly list all available methods and properties. You have to somehow piece it together from various ABCs. [2] Compare this to, e.g., Rust's online doc of its Vec type. [3]

[1] https://docs.python.org/3/library/subprocess.html#using-the-...

[2] For example, lists: https://docs.python.org/3/library/stdtypes.html#sequence-typ...

[3] https://doc.rust-lang.org/std/vec/struct.Vec.html

help(list) quickly provides a list of all available methods and properties, as does help([]). Is that what you mean?

I was refering to the online documentation. Yes, the interactive docs are sometimes better.

This isn't true. All sort of people - even the most incentivized to find out a specific information - benefit from a sort of short summary in the form of a FAQ section.

Sure, some can see FAQ as a patch, but I don't see how they can't be a valuable addition even to a well laid out website where information is easily accessible. The two things aren't mutually exclusive.

> If people are frequently asking the same question then your information and how you deliver it is lacking.

I maintain a FAQ mostly for things over which I have no control,

https://www.reveddit.com/about/faq/

Each question comes from a user's comment somewhere, and I often link back to it when answering new questions. I'd be interested to hear if people would prefer a different format or different wording.

Yep, but those are actually Frequently Asked Questions, what I cannot bear is the use of FAQ (and their page) on a brand new site, where there has not been time enough for any "real" question to have been asked by the user.

It is only a (poor) literary form and since they are (mostly) prefabricated, they are either unneeded/duplicated (as the topic is properly explained in the main site/docs) or actually showing that the original text/docs/instructions are not clear enough (and since the Author has control on those, they could be rewritten/amended/corrected to make them more clear).

And - more correctly - they should be FGA's:

https://web.archive.org/web/20201231033026/https://jdebp.eu/...

https://web.archive.org/web/20201231033031/https://jdebp.eu/...

For me biggest issue are synthetic FAQs because they don't really offer anything that documentation would not. Worst offenders are when CEO tells some intern that they need FAQ on the page so that people can see that other people are asking questions about product ;)

Ideal FAQ lets you search or has questions in a way real person would ask, as those should be written down in a way most people asked such questions. We could even have index of multiple forms of the same question pointing to the right answer.

Problem with documentation is that it is not written there to answer questions. It is written from perspective of "how system works" so someone just writes it down.

For technical documentation like a language I don't expect much need for an FAQ because audience should be able to pose questions and answer those by themselves and then search what is provided like a manual.

For web application or government websites that general audience should use I don't see "documentation" approach viable, you need "Questions and Answers" approach.

Python documentation is not amazing. Search is poor, I expect nowadays instant structured search. Table of contents is generally useless. And important information like common usage is not displayed upfront. Python docs might be great for learning concepts for the first time but not for quickly consulting stuff.

> I can’t think of a single TypeScript issue I’ve run into that hasn’t ended with me going through an infinite amount of web searching and wading through a gazillion useless suggestions

Reading unit tests for me has been my go-to for getting around problems in TS/JS documentation in libraries. Unit tests can sometimes be unintentionally the best documentation. Also helps filter out quickly libraries you'd want to avoid at all costs. No unit tests means you're putting untested code into your system.

> TypeScript/JavaScript (where the documentation is horrendous)

Clearly you've never had to do anything in VBA....

Reply on news.ycombinator.com