Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Examples are the best documentation

rakhim.exotext.com

Post reply on HN
Print view View original

31–40 of 179 posts

Re: Examples are the best documentation

#31

Post by troupo »

Paracompact wrote: post #27

Radical opinion: If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, the method is probably trying to do too many things. In particular, I don't want to have to learn half a dozen footguns because of a leaky abstraction.

No. Examples are there to show how to use this method, and other methods in conjunction.

You can intuit all you want from a method signature, and then you will fail to produce working code because you missed a config, or a preparation step, or don't understand how to process the results, or...

Re: Examples are the best documentation

#32

Post by snthpy »

bigstrat2003 wrote: post #28

Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both .

Totally agree but there is tldr for that.

I learned recently that tldr also has separate pages for subcommands.

Re: Examples are the best documentation

#33

Post by voidUpdate »

This sort of thing really bugs me when I work with Unity and Unreal. Sometime the documentation for something is just so useless. A lot of the time when trying to understand Unreal nodes, the documentation page is just a picture of the node and the name of the node restated in slightly longer words, as if that helps anything. And so many times when I'm using Unity at £JOB, I just want to know how to use a function properly, and a short example would help so much. It's generally good but some pages just have nothing of value on them. If I could submit my own additions to the Unity docs pages, I would probably end up doing that

Re: Examples are the best documentation

#34

Post by undebuggable »

bigstrat2003 wrote: post #28

Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both .

It already exists - tldr. Use it side by side with man.

Re: Examples are the best documentation

#35

Post by jopsen »

gbalduzzi wrote: post #22

You need both and there are no ways around that. Examples let you grasp immediately how to use the library and provide you good starting point for your integration. Detailed explanation of all params and configurations allows you to solve more complex problems and understand the full capabilities of the tool. I am miserable when any of the two kind of documentation is missing. The only exceptions are very simple libr…

Agreed, examples and reference docs.

When feasible, I'd add repl environments. The ability to quickly modify and test the example can make up for a lot of the shortcomings documentation might have.

Re: Examples are the best documentation

#36

Post by musebox35 »

smokel wrote: post #21

The Diátaxis framework [1] provides a nice suggestion of different types of documentation, and when to use them. None of these types is "best", each serves a different purpose. [1] https://diataxis.fr/

I think conceptually diataxis is brilliant. However, it is not trivial to implement. Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective. The ratio also evolves with community adoption and expertise level. I really wish it was simply more actionable. Documentation is a hard problem, maybe we will figure out a better way one day. Until then docs will only be as good as the amount of time and expertise spent on them, which is usually not as high as it should be due to resource constraints.

Re: Examples are the best documentation

#37

Post by dotancohen »

snthpy wrote: post #32
bigstrat2003 wrote: post #28

Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both .

Totally agree but there is tldr for that. I learned recently that tldr also has separate pages for subcommands.

tldr was created specifically to address this miscoming of the manpages. And it's recent enough to not ship with any distros.

Re: Examples are the best documentation

#40

Post by oneeyedpigeon »

bigstrat2003 wrote: post #28

Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both .

I'm always pleasantly surprised that many man pages do have examples. But, sure, they could be a lot more comprehensive.
Post reply on HN