Comment by sumtechguy | Hacker News Reader

Comment by sumtechguy | Hacker News Reader

Parent Full thread

I just wish many of the docs were better.

I see this 'style' many times in some docs. A bit of doc that basically describes the name of the function/class. But does not show why and how to use it, how it fits in the API system, and so on.

public void DoesXYZ()

Then many times a description of 'a public method that does XYZ' does not return anything.

It is exceedingly unhelpful but meets the 'it is documented' checkmark.

My next step would be to search for an example usage of that thing (usually landing on something like SO or some random training site). Then what sorts of items might it need to work. Why would I use it over something else? Some OK examples of what is going on goes a long way and what sets the expectation of the original dev on how they were expecting you to use it. So I end up spending some decent amount of time reading the tea leaves and if I am lucky the code itself to decode what is going on.

One feed back I consistently give to all vendors is 'your docs need examples and those examples need to be consistent with each other' If I have to open github and spend a few hours reverse engineering that code, and then also try to learn whatever language you thought was fun to play with 6 years ago, I am not going to be happy.

Exactly. Examples always trumps some convoluted explanation.

Good docs are like: "this library make you do things like this, this or this, as easy as [show code snippet 1, 2, 3]".

Also a big list of examples should be way easier to just dump into the docs than writing some absurdist essay about the tech, ie. it's even easier for the maintainers.

I vaguely remember the PHP website doing this with their functions on their website with user comments with examples - another example is Mozillas MDN.

Honestly now thinking about it, "user added examples" should be its own category on sites like Github. Seriously why isn't this a thing?

Dozens of "Here's how i used this library to do this" would be amazing.

That's just lazy javadoc style. The worst kind of documentation, since it adds nothing over looking at code itself.

At the very least, there should be examples of usage.

I never did PHP, but they have one of the best documentation features: comments. It allows you to recognize if a function is a footgun: https://www.php.net/manual/en/function.utf8-decode.php

There is a difference between documentation and tutorials.

Very much so. But many times just a small example putting the thing in context of usage helps a lot. Sometimes that is needed sometimes it is not. This style is especially useful if you have a call/anticall style like malloc and free. An example of malloc could also have an example of free along with it indicating to the reader (hey you want this too). Some docs it is not obvious what the matching call is.

Reply on news.ycombinator.com