Ask HN: Why are documentation only showing 1 example if any

https://news.ycombinator.com/item?id=24939227

by julienreszka • 6 years ago

13 13 6 years ago

news.ycombinator.com

It's now pretty clear that learning is more effective when you have a larger dataset of examples. Why are programing documentations only showing one example per function, if any, instead of dozens?

gostsamo• 6 years ago

Because writing documentation is boring and done by volunteers. Unpaid people tend to do stuff that is interesting for them, not useful for you. Even paid people tend to do the same if not pressed, so what you get is what you pay for.

viraptor• 6 years ago

Depends on the documentation. Here's 20-ish examples for one function: https://relishapp.com/rspec/rspec-mocks/docs/setting-constra...

If you have people and time for docs, you'll have good docs.

de_watcher• 6 years ago

We just have automatic tests that use the thing in every possible way. We have them because that's how we've developed and debugged the function. Best documentation ever.

tcbasche• 6 years ago

A comprehensive unit test suite is the best documentation your code can have :)

1_player• 6 years ago

On the opposite, and more irritating side, you have documentation like Ansible's where the core functionality is only explained by examples.

I would've loved to know the exact format of the inventory file specified on a single page, or the list of all supported Jinja methods with a quick description of each, but no, pages and pages of just conversational examples.

Which is great when starting out, and absolutely awful past that, so you is click through maybe relevant pages and Ctrl-F what you're looking for.

zufallsheld• 6 years ago

To add, I like ansibles module documentation. Every option is explained and most times there is more than one example in how to use the modules.

disposedtrolley• 6 years ago

Quality documentation is very difficult to produce and maintain.

On top of adopting a different mindset when writing docs (you'll need to phrase concepts and provide examples to cater for users who probably don't share the same intimate knowledge you have of the codebase), there's a high cost associated with upkeep. Ensuring that your docs always align with the implementation might be straightforward for smaller applications, but as your API surface grows so will the cracks that outdated documentation will slip through.

There are a few examples of tools which are designed to lessen the burden (that I know of):

- To generate usage examples from your code, Go has the idea of testable examples (https://blog.golang.org/examples) which get rendered in the documentation but are declared as normal functions. These can be easily unit tested.

- To provide usage examples in code without resorting to unit tests, Clojure has `comment` forms (https://clojuredocs.org/clojure.core/comment) which are normal expressions but ignored by the compiler. You can define arbitrary expressions within a comment form (e.g. to execute another function), so these can be used to define usage examples and placed next to the functions they call.

bjourne• 6 years ago

Because programming documentation is often written by programmers and not teachers and most programmers doesn't know how to teach. Documentation without any (or few) examples is like math textbooks with only proofs and no exercises.

fiftyacorn• 6 years ago

If it's open source the unit tests are often the best place to start for examples

iordachej• 6 years ago

PHP just let the community write examples in their docs and the results were spectacular. Some years ago they removed that part but had to put it back shortly due to massive requests. Could be one of the key decisions they made at the very beginning that turned their language into one of the most popular ever made

thirtythree• 6 years ago

Most documentation is bad and seems to promote formality over usefulness. Examples go a long way.

The most recent example of good docs I have come across recently is svelte.dev

HybridLightAI• 6 years ago

In a perfect world most software would have a wiki page that would have dozens of examples showing proper usage. That would certainly help me a lot.

taphangum• 6 years ago

This might add some insight into the problem. https://fromtoschool.com/why-most-programming-tutorials-are-...

Ask HN: Why are documentation only showing 1 example if any

Related Stories