Examples are the best documentation • Hacker News Board

Re: Examples are the best documentation

#71

Post by teamonkey » Fri, Oct 10, 2025, 12:37 PM UTC

voidUpdate wrote: post #33

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 pr…

Unreal's lack of documentation is hugely frustrating and a massive time sink for me. They very much subscribe to a 'code is documentation' approach (I don't agree), but the 'screenshot of a node' documentation for blueprint is truly beyond parody.

Re: Examples are the best documentation

#72

Post by voidUpdate » Fri, Oct 10, 2025, 12:42 PM UTC

teamonkey wrote: post #71

voidUpdate wrote: post #33

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 pr…

Unreal's lack of documentation is hugely frustrating and a massive time sink for me. They very much subscribe to a 'code is documentation' approach (I don't agree), but the 'screenshot of a node' documentation for blueprint is truly beyond parody.

I also had some issues recently where I was trying to build something in the latest Unreal version, and the docs for the thing I was trying to do said they were for that version, but obviously had screenshots from the last major version, which had a completely different interface style and menu items in different places, and as such was almost completely useless. Someone forgot to check it before bumping the version number on the docs

Re: Examples are the best documentation

#73

Post by woooooo » Fri, Oct 10, 2025, 12:44 PM UTC

tmoertel wrote: post #56

Say what you will about Perl, Perl docs are some of the most helpful. It's standard for docs to have a SYNOPSIS section up front that provides examples of common usage. This is followed by discussion, reference, and often more examples. For example: https://perldoc.perl.org/bigrat https://perldoc.perl.org/Archive::Tar If you're writing docs for your project, consider following the Perl documentation style. Fortunatel…

I did a bunch of perl in the early-00s, then never touched it again until a random engagement in 2014. It came back IMMEDIATELY. Felt like having conversations with an old friend.

I don't know what it is, its definitely not mathematical purity or consistency, but there's something there witb Larry Wall's linguistics background and general attitude that just stays with you.

Re: Examples are the best documentation

#74

Post by inetknght » Fri, Oct 10, 2025, 1:02 PM UTC

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 haven't had that problem. I just code something up, and poke around to understand some of the terms that it's talking about. Then I start reading about error return codes, why them happen, what kinds of parameters actually mean, etc. No examples are usually needed as long as documentation is complete

The most frustrating things are things that are undocumented at all and only have examples. What the hell kind of shitty documentation is just examples with no idea what parameters could or shouldn't be?!

Re: Examples are the best documentation

#75

Post by somat » Fri, Oct 10, 2025, 1:08 PM UTC

Documentation comes in two halves, the examples and the reference, the examples are nice to understand how everything ties together, the reference explain how things work. If I only had one I would pick the reference. But having said that there have been times I would have killed for a simple example.

When I am learning something, I do tend to start with the examples, it is the best way to quickly get a feel for the shape of the domain and it's usage. But then end up in the reference in order to understand and apply what I just learned.

Re: Examples are the best documentation

#76

Post by bluGill » Fri, Oct 10, 2025, 1:09 PM UTC

harimau777 wrote: post #70

Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function. Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I nee…

Both are needed for good documentation. You start with the details and then finish with a few examples so that someone who has read the details can check their understanding. Sometimes the example is all you need, but most often there are far more possible combinations of options such that an example of all the useful ones would be several books long (there is no good way to sort/index them so someone wouldn't find the example they need if you wrote them all). So you start with an explanation of each option, and then a few examples that are as different as you can make them so readers get a sense of what is possible and can look back to the explanation to figure out the changes they need to get the example to do what they need.

Good documentation is hard, and very rare these days.

Re: Examples are the best documentation

#77

Post by bluGill » Fri, Oct 10, 2025, 1:10 PM UTC

skydhash wrote: post #9

happytoexplain wrote: post #8

Earlier quoted context omitted.

Examples are often crucially valuable, not just for beginners. Some of them can inject in five seconds an understanding equivalent to an hour of reading the very-objective docs and experimenting. I'm thinking of some git doc pages. But it applies just as well to single functions that are very simple conceptually, but hard to describe clearly and briefly and completely. The developer has time for neither or both. Once…

[flagged]

Even as an "expert with several decades of experience" there are so many parts to a complex system that I still am a beginner in.

Re: Examples are the best documentation

#78

Post by codazoda » Fri, Oct 10, 2025, 1:12 PM UTC

I use ImageMagick a lot and kept finding myself Googling for examples. I started writing notes for myself and recently combined them into a small field guide of command-line examples.

I go on to explain each of the arguments, however, which this blog post doesn't necessarily suggest. I think we need both examples and explanations.

My draft is still early, but it’s already useful for everyday tasks like resizing, optimizing, and layering.

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

Re: Examples are the best documentation

#79

Post by nmcfarl » Fri, Oct 10, 2025, 1:12 PM UTC

skydhash wrote: post #9

happytoexplain wrote: post #8

Earlier quoted context omitted.

Examples are often crucially valuable, not just for beginners. Some of them can inject in five seconds an understanding equivalent to an hour of reading the very-objective docs and experimenting. I'm thinking of some git doc pages. But it applies just as well to single functions that are very simple conceptually, but hard to describe clearly and briefly and completely. The developer has time for neither or both. Once…

[flagged]

I’m not sure if that’s true.

The number of times I’ve opened FFmpegs man page must number in the hundreds. I think I’m a pretty good conceptually, but I can’t remember all the flags. IE that –s is frame size, while -fs is file size.

And while that man page does have some examples, these days I tend to ask an LLM (or if it’s going to be simple Google) for an example.

Re: Examples are the best documentation

#80

Post by btbuildem » Fri, Oct 10, 2025, 1:27 PM UTC

This holds true for product documentation as well. Too often docs are just a litany of detailed feature descriptions, which field and button does what, etc.

Feature-list type documentation is orders of magnitude less useful than workflow-type documentation. Majority of the time users are concerned with accomplishing tasks, which if the software is well designed, can be grouped, composed, and illustrated with examples. Key examples can be chosen to both showcase features and illustrate the main paths from "raw materials" to "finished workpiece", at various scopes.

This gap is too often filled by random youtube tutorials of varying quality. It's really telling of the massive blind spot afflicting the makers; they're too close to the details of what they build to see the whole, especially from the perspective of a user.