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

171–179 of 179 posts

Re: Examples are the best documentation

#171

Post by inetknght »

chaorace wrote: post #107
inetknght wrote: post #74

Earlier quoted context omitted.

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

Sometimes, I just wanna remind myself how to use xargs for some command text replacement in a random one-liner on the terminal. If I tried to do that with man... I'd have to read (in alphabetical order) the documentation for 6 different command flags. That's how far I'd go to read about the flag -- to actually use it, I'd have to experiment with the command flag until I figured out the actual syntax using my imaginat…

Once you have something working the way you like, make your own example and put it on a github repo named "today-i-learned". Then you can refer to it as your own documentation for yourself.

Re: Examples are the best documentation

#173

Post by ranger_danger »

satisfice wrote: post #18
ranger_danger wrote: post #14

Earlier quoted context omitted.

Personally I am much more tired of lengthy troves of API docs that, while fully specifying the system, do nothing to specify how one is actually supposed to use it in practice, such as the general flow of the program itself, which functions are relevant to what overall operations, in what order certain functions should be called relative to others, how one should handle errors, etc. If I at least have some examples t…

I agree that code is not documentation. I agree that automatically generated API docs from code is nearly useless. I agree that examples are important and useful. But examples are not "the best documentation." Or I should say hyperbole is poor documentation of one's point of view.

Are you saying everyone else's opinion of "best" is wrong other than yours?

Re: Examples are the best documentation

#174

Post by tialaramex »

SAI_Peregrinus wrote: post #92
tialaramex wrote: post #41

Earlier quoted context omitted.

Right, one of the best out-of-box tooling decisions for Rust is that by default, and out of the box cargo will assume all your documentation examples are tests it should compile and execute. This means so long as you run the tests before shipping you basically can't ship with examples you forgot to update after an API change because they either don't compile or don't work. And you might think well, nobody would ship…

I'd go a bit further and say that all tests are documentation examples. Rust is nice because it has symmetry and documentation examples are tests.

Ah, I do actually have some "real" unit tests where what I'm testing is not directly exposed to users. So e.g. code to correctly find how many bits of precision I need to calculate the decimal output in realistic::Real is tested but users can't ask that so there's no value in documenting it.

Re: Examples are the best documentation

#175

Post by snozolli »

sfn42 wrote: post #128
snozolli wrote: post #122

Earlier quoted context omitted.

Everyone who disagrees with you are amateurs. "No true Scotsman would want examples." I'm far from an amateur and I want to see several concise examples in documentation. That doesn't mean that's all I want to see.

That's not what anyone said. We both said examples are great. They're just not more important than proper API docs. They're not the best. The best is thorough api docs. The rest is nice to have. And I'm not no true scotsmaning, I'm just saying most devs are ass. I know, I see people with 20 years of experience on me write buggy trash code that I have to fix. I see people whine about the java docs as if they aren't so…

That's not what anyone said.

That's exactly what you said.

And I'm not no true scotsmaning

You absolutely were. Now you're trying to backpedal.

Re: Examples are the best documentation

#176

Post by scubbo »

sfn42 wrote: post #127
scubbo wrote: post #106

Earlier quoted context omitted.

> You optimize for power users not amateurs. Sure, but you can optimize for one without excluding the other. Adding examples _allows_ amateurs to gain experience and _become_ power user, and imposes near-zero cost on power users who can just skip a couple lines and get into the "real" API doc.

Nobody said don't add examples. Just don't do it before creating proper API docs.

That's on me - I over-focused on the leading sentences/paragraphs of the replies ("Please don't follow this advice [that examples are the best documentation]"), and missed that the first comment had "Also having examples is fine, but they should be considered a bonus" in the last paragraph. You're right!

Re: Examples are the best documentation

#177

Post by theshrike79 »

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…

How about the Go style where examples in documentation are actually run as part of the test suite: https://go.dev/blog/examples ?

This way the examples must always be valid and runnable.

Re: Examples are the best documentation

#178

Post by tomashm »

tldr; Adding key examples to a specification makes it much easier to understand.

I learned programming with Pascal at university. It had a very formal, math-like syntax, complete with BNF-style grammar.

The next course used the famous K&R book (The C Programming Language), and what a breeze that was! It taught by showing lots of relevant, working examples.

Since then, I’ve realized that while examples aren’t a substitute for a clear specification, well-chosen examples make specs far easier to grasp.

I recommend reading Gojko Adzic’s thoughts on this (https://www.linkedin.com/in/gojko/). He’s the author of Specification by Example.

He argues that identifying and refining key examples is a great way to raise the quality of documentation and shared understanding.

Re: Examples are the best documentation

#179

Post by musebox35 »

nevertoolate wrote: post #48
musebox35 wrote: post #36

Earlier quoted context omitted.

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…

I'm not sure what you mean by > Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective I think Diátaxis _is_ mostly a conceptual framework. It helps me tremendously, totally implementation agnostic. From the site itself: > Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it’s a com…

I totally agree with your assessment. I just wanted to highlight that “implementation agnostic” is both a blessing and a curse. You can always apply the principles of diataxis but it provides near zero guidance on how to actually build the documentation for a specific project. This does not reduce its conceptual value, but I wish there was another framework with a complementary practical value.
Post reply on HN