9 ms·
Examples are the best documentation
- willquack 1y agoCode examples can be executed as unit tests to prevent documentation regressions / bitrot in ways human language can't
- actionfromafar 1y agoBut now with LLMs maybe they could begin to check for instance API documentation.
- theamk 1y agoExamples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list. Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? How do I pass in content-type? Does raise_for_status ignore 204? Both have their merits, but if developer only has time for one, I'd go for proper doc. [0] https://requests.readthedocs.io/en/latest/user/quickstart/ https://requests.readthedocs.io/en/latest/user/quickstart/
- GenericDev 1y ago[dead]
- happytoexplain 1y agoExamples 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 the productivity barrier for one has been broken, the other is a tiny extra effort. In that case, they must provide both, except in the small minority of cases that are exceptionally self-describing, where one (usually docs) is sufficient.
- skydhash 1y ago[flagged]
- bluGill 1y agoEven as an "expert with several decades of experience" there are so many parts to a complex system that I still am a beginner in.
- nmcfarl 1y agoI’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.
- skydhash 1y agoThat's why the recommended practice with shell usage is to write a script (or alias or function) and to use the long version of the flag in the script. Instead of having a complex invocation of ffmpeg, you'd have `flac2mp3 -q low file`.
- pixl97 1y ago>Examples is for beginners. No, not really, or I should say simple examples are for beginners. Typically when I'm writing example pages I write it in Simple example Simple example Simple example Intermediate example Intermediate example Complex example. Having complex examples can really help those that are looking at going beyond the basics.
- konmok 1y agoI agree. Good documentation (nearly) fully specifies program behavior, and doing so with just examples is impractical or impossible.
- preommr 1y agoIt is order of magnitudes easier to understand behavior through examples than through a reference-like documentation. People suck at naming things, and then documenting them. Just today I spent the last few hours trying to figure out how to get something to work because a parameter only worked if another paramter had a specific value. There was too much magic to try and figure out the code, llms wrongfully told me the latest version doesnt support the parameter because it couldn't find any documentation. Ultimately, creating a small example that I know should've worked and changing things in a way that I could narrow down the problem worked best. The point to all this is that examples often encapsulate multiple things into a condensed format, that is extremely high fidelity (since it's typically a code example that runs and has output). Things like Api documentation in comparison typically cover a huge surface area, and have way less effort in maintaining them. Also for the record, I absolutely don't trust libraries on behavior that isn't extremely obvious, explicit and so absolute that it's almost effortless to find out (I am talking first thing on README, entire sections showing that one thing, or definition through types). I just assume that things like behavior around status codes are going to change, and do my best in the calling code to mitigate issues as much as possible.
- freetonik 1y ago>occasional users That's exactly what I'm pointing to in the post: >When jumping between projects, languages and frameworks, it takes a considerable amount of mental energy to restore the context and understand what is going on.
- dwenzek 1y agoA proper doc definitely has to provide the details. However starting with an example or two is a nice way to a give the users a quick overview. Even better when this example is interactive as for redis where you even have an example use case. See https://redis.io/docs/latest/commands/incr/ https://redis.io/docs/latest/commands/incr/
- golyi 1y agoThey're not mutually exclusive you know, you can have both example and a proper technical doc.
- _0ffh 1y agoTook the words right outta my mouth! Of course we want a full list of public functions with all the info. But with just a list of functions it's often still not quite clear how you're supposed to setup and call them, unless you dig through the whole list and try to understand how they interact internally. A few short examples on "How do I init the library/framework so I can start using it", "How do I recover from a failure case", etc. makes the docs infinitely more accessible and useful!
- abacadaba 1y agoUnfair example google has the worst docs in existence. Either a quickstart with one uselessly simplistic example or an autogenerated class list on a totally separate site with no explanations to be found. Often I just end up looking at their libraries source code to learn how to use it.
- xchip 1y agoalso unit tests
- thebestmoshe 1y agoI’d say the part of the unit test that is helpful is the example of using the code. It has a pro over documented examples in that they are _guaranteed_ to be correct.
- NedF 1y agoThis is why LLMs won. Useless documentation means half-arsed is better. The world of IT is broken, what sort of idiot gives Linux to their parents when as a trained developer man is so useless? It's just excuse after excuse. Unit tests are documentation sort of garbage. That's what's mind blowing about LLMs, IT devs are so bad LLMs are better. Hacker News comments also confirm this.
- wiredpancake 1y ago[dead]
- jpollock 1y agoThe form the documentation takes depends on the audience. If the audience is teammates, the _code_ itself is usually the best documentation. Tests lie about edge cases. A test _might_ be demonstrating an edge case, or the suite might ignore large sections of edge cases. Documentation is worse, it rarely documents edge cases. Country Y passes legislation and you need to implement it? Yeah, the docs aren't getting updated. If your audience is a different team, API references (the headers/RPC message schema/javadoc/etc.) are better than written docs. Again, they are less likely to mislead you and are much more likely to work. Unless, of course, the interfaces are telling fibs about what is allowed. Interfaces that are big buckets of parameters can do that. Only if your audience is an external organization would documentation be a good primary reference. It meets them where they are, selling them on the capabilities of the software and bootstrapping them to the code.
- satisfice 1y agoThey are not the “best.” They are helpful. I am tired of rudimentary docs that only have examples.
- ranger_danger 1y agoPersonally 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 to get me started, then I can go digging through other documentation (or even just the code) to figure how to do more advanced things... but being unable to even get started is a much bigger frustration IMO. One time my company paid $5k for a commercial x264 license, and when we asked for some documentation on how to get started with encoding some video frames using their C API, they simply responded "the code is the documentation." With no real examples to go on (at the time in the 2000s there actually wasn't much available online at all), this set me back a good two weeks that I felt was completely unnecessary and completely turned me off to interacting with them at all for the future. We ended up switching to a hardware solution that was much easier, faster, well-documented, and way friendlier people to talk to.
- satisfice 1y agoI 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.
- ranger_danger 1y agoAre you saying everyone else's opinion of "best" is wrong other than yours?
- skinkestek 1y ago
- alliao 1y agoexamples often show the "spirit" of the invention it's intended usage if you like, which explains more what it does than name alone... also reason why I prefer wordy development notes than just a list of parameters it's useful for me to know whether it's what I want quicker than what I think I want based on name
- adzm 1y agoObviously you want detailed documentation too, and examples are great for quickly grasping bigger concepts and how to integrate into other systems. In my experience the best solution are both, where examples all have hyperlinks to the actual documentation for everything involved in the example. React is a good example in my opinion; there is detailed documentation of the api, overviews of the concepts, as well as examples that are included where necessary and as part of a walkthrough. Even better are the challenges at the end of their examples which force you to rethink what you just read.
- theletterf 1y agoThe best docs are the ones that satisfy user needs. https://passo.uno/seven-action-model/ https://passo.uno/seven-action-model/
- smokel 1y agoThe 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/ https://diataxis.fr/
- musebox35 1y agoI 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.
- nevertoolate 1y agoI'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 complete mess by any standards - it’s always possible to improve it, iteratively.
- musebox35 1y agoI 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.
- zahlman 1y agoThis really should be at the top. It was almost frustrating seeing how much other discussion there was here before finally finding mention of Diátaxis. Examples are crucial to documentation, but they aren't — at least in this view — a kind of documentation, so much as a technique for documenting.
- gbalduzzi 1y agoYou 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 libraries, where the example tells you already everything there is to know.
- jopsen 1y agoAgreed, 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.
- joemi 1y agoI'm honestly surprised there are people who think that only examples are fine. And I'm equally surprised there are people who think only reference docs are fine. It's so infuriating coming across a project that only has one kind and not the other.
- gorgoiler 1y agotldr.sh is a project that had been doing this for man pages: https://news.ycombinator.com/item?id=15779382 https://news.ycombinator.com/item?id=15779382 As the above 8y old discussion and today’s blog post both say: yes, examples are but one part of a complete set of learning materials — practicals, theory, recipes, reference. However, in a toss up, the greatest of these is the one you always want first: picking the thing up, tossing it about to get a feel of it, and getting your hands dirty! For code, worked examples are particularly helpful because your dev environment can jump to the function definition, which typically has its own reference documentation.
- basemi 1y agoExamples are the best `quick start` documentation. Comprehensive manuals/references are the best documemtation.
- ossusermivami 1y agowhen possible (python, golang and many others) I just go and read the source..
- Paracompact 1y agoRadical 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.
- troupo 1y agoNo. 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...
- Paracompact 1y ago> because you missed a config, or a preparation step If the specific values of parameters of your mutable state are material to the outcome, then the example is incomplete if they are not specified. Similarly, you wouldn't use `fib(x) = 3` as an example without specifying `x = 4` in your context. > don't understand how to process the results Not sure when this would be the case. Do you have an example in mind?
- troupo 1y agoReal world isn't about calculating a fibonacci sequence. Real world is usually a combination of - read data - trasform data - obtain auth - prepare data in proper formats - <the only step usually shown in examples here> - get results back. Perhaps an error? A stream? A specific format? Could we do retries? That's why a full example would look like this: https://developer.auth0.com/resources/labs/actions/sync-stripe-customers-and-auth0-users#introduction https://developer.auth0.com/resources/labs/actions/sync-stri... or https://github.com/stripe-samples https://github.com/stripe-samples and not a "it's enough to deduce parameters from method signature"
- Paracompact 1y ago
- bigstrat2003 1y agoSimilarly, 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.
- snthpy 1y agoTotally agree but there is tldr for that. I learned recently that tldr also has separate pages for subcommands.
- dotancohen 1y agotldr was created specifically to address this miscoming of the manpages. And it's recent enough to not ship with any distros.
- undebuggable 1y agoIt already exists - tldr. Use it side by side with man.
- oneeyedpigeon 1y agoI'm always pleasantly surprised that many man pages do have examples. But, sure, they could be a lot more comprehensive.
- greenbit 1y agoI've developed the habit of checking the end of the page, because that's where the examples are, when there are any.
- childintime 1y agoPHP documentation stands out with the comment section, like an integrated stack overflow, with examples and gotchas. It's what made PHP great.
- WalterBright 1y agoEven better if the documentation examples are part of the test suite!
- tialaramex 1y agoRight, 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 examples that don't even compile right? But on more than one occasions I've used a Microsoft C# library that comes with examples clearly hand made by their engineers (yes I'm that old that it couldn't be LLM output) without checking they work. Somebody has sketched out what ought to work, they haven't tested it, and a reviewer has seen that it looks right and OK'd it, but again, never tested that it works. This is extremely frustrating because the documentation is wrong but now what?
- SAI_Peregrinus 1y agoI'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.
- tialaramex 1y agoAh, 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.
- WalterBright 1y agoThe dlang website generator does not succeed unless all the coding examples run successfully.
- 1y ago
- voidUpdate 1y agoThis 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
- squigz 1y ago> £JOB Wait a second, do people use $ for `$job` because it's how they earn money and not, as I've always thought, used it as a variable name? Stop throwing my entire world view out of order please.
- voidUpdate 1y agoI actually don't know, I just assume the majority of people are americans and that's why they use $. I don't use $ in programming except for string interpolation, so it's never really registered as a variable sigil to me
- squigz 1y agoOh no my PHPness is showing! Also, many, many countries use $, like Canada.
- tom_ 1y agoIf you think it would reflect on you better, think of it as indicating regular POSIX shell use?! (I'm 99% sure it's intended to be reminiscent of that sort of syntax. Example use: https://news.ycombinator.com/item?id=42761939 https://news.ycombinator.com/item?id=42761939)
- zahlman 1y ago
- semv3r 1y ago[dead]
- citrin_ru 1y agoIt's a false dichotomy good documentation should have both - comprehensive reference and examples.
- p0w3n3d 1y agoCarefully chosen examples are best documentation. Badly chosen examples are a mediocre documentation.
- tremon 1y agoIn terms of actually documenting something, examples are not documentation at all -- they are merely illustration. The annotations accompanying the examples (if any) are better documentation than the examples themselves.
- noirscape 1y agoLike a lot of advice for documentation, it's not completely accurate. Good documentation should cover 3 "kinds" of users. * Absolute beginners/newbies: These users are best helped by showing a "happy path" through the tools, with plenty of examples to show you why things are that way, so they build up an understanding of how things are supposed to work. * Regular users: These are best helped by a "topic" oriented style of documentation. Topics can take one element of a tool and go really in-depth on it. For example, a HTTP request library might have a topic page entirely dedicated to session authentication, explaining how to persist headers and cookies between requests in the library and what a session object does. * Power-users/developers: These users are served by reference docs the most. Just a big index of classes, functions and argument doc strings that refer to each other is enough here, because anyone reaching for reference docs is usually doing it because they have a very specific issue. As for real world examples I'm familiar with; NodeJS libraries often only have beginner docs, and the moment you go off of that happy path it becomes very difficult to reason about what you're doing (not helped by a lot of frameworks preferring you use CLI tools to build up your code, maybe this has changed), the python ecosystem often has good topical docs at the cost of poor reference documentation and C libraries very often only ship with reference documentation. Programming-wise, it's easy to make reference docs (since they can be derived from comments in the source code) and beginner docs (because you probably have a mental model on how someone is meant to start using something), while writing good topical documentation is an entire skill on its own (since it requires understanding where someone might struggle with something.) The best documented tools usually have all three covered at the same time, while poorly documented tools usually only have beginner or reference documentation. Only having beginner docs makes it impossible for someone to really learn a tool ("draw the rest of the fucking owl"). Only having topical docs makes it hard to figure out where to start. Only having reference docs is hard to reason about because there's nothing explaining to you how the references are meant to fit together.
- IshKebab 1y agoOCaml is really bad for this. Zero examples in its docs. The best docs with examples I've seen are Qt (probably the best documentation overall), Rust and Go.
- constantcrying 1y agoExamples are the best Documentation to learn. If you are deeply knowledgeable about some library or language, examples become less valuable and the straight forward API documentation becomes essential.
- ssl232 1y agophp.net was great for this back in the 2000s.
- jgalt212 1y agoI agree. When we moved to Python, I really missed all the examples that php had that the Python docs didn't.
- tmoertel 1y agoSay 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/bigrat https://perldoc.perl.org/Archive::Tar https://perldoc.perl.org/Archive::Tar If you're writing docs for your project, consider following the Perl documentation style. Fortunately, that style is itself well documented: https://perldoc.perl.org/perldocstyle#Description-and-synopsis https://perldoc.perl.org/perldocstyle#Description-and-synops...
- woooooo 1y agoI 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.
- adrianmonk 1y agoThe examples in the Perl documentation are very well chosen, too. They aren't just a quick way to get up to speed. They aren't just code that you could use as a starting point and modify for your purposes. Instead, many of them are almost like exercises to help you work through the ideas that the documentation is presenting. Some of them help you see how a syntax or other language rule applies. Sometimes the documentation presents two pieces of example code and walks you through why they're equivalent, helping you understand the language better. Or why they're almost equivalent and what the differences are. In a lot of documentation, examples give you a superficial understanding but are a dead end if you want to go beyond superficial. In the Perl documentation, examples are often a bridge to a deeper understanding.
- layer8 1y agoWhile there is often a lack of examples in documentation, a lack of cogent conceptual explanations is unfortunately even more widespread.
- huem0n 1y agoI wish it was a linter rule that people can't add type-hints until they've added at least one example.
- 6510 1y agoExamples are also terrible as people will confuse them for the subject.
- dewey 1y ago> One popular community-based project in the Clojure world is clojuredocs.org, a site where people contribute examples for built in functions When I was learning php in school, the examples / discussions on every documentation page were always the most helpful bit.
- synergy20 1y agowait, isn't this a just-solved problem by asking your AI?
- lvturner 1y agoOnly if it's aware of your platform/programming language/etc
- harimau777 1y agoPlease 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 need to fix a problem or actually learn the library. Also having examples is fine, but they should be considered a bonus; not documentation.
- bluGill 1y agoBoth 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.
- skeeter2020 1y agoDocumentation is like the system it supports too: the only unchanging ones are those nobody is using! I think this is obvious when we compare quality between the historically much slow manual releases with the cadence today, and the documentation of relatively slowly changing projects with newer, faster ones. It's a lot of work to create good documentation; it's even more work to keep it good.
- infecto 1y agoI don’t fully agree. Javadoc style documentation should be programmatic and driven by types and inline doc strings. It should just always exist and I would argue having it online is ok but why would not just go to the code itself. Examples like QuickStart guides should absolutely be required. They serve as the quick entry point and general use of the library. If I only had the code docs I would have no idea how I am supposed to use the api and was my main complaint of many Java libraries historically as they only had a Javadoc.
- somat 1y agoDocumentation 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.
- codazoda 1y agoI 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 https://news.ycombinator.com/item?id=45538609
- btbuildem 1y agoThis 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.
- pixl97 1y ago> than workflow-type documentation. Yes, for api/token interactions I love examples that show how to generate a token with only permissions for what you are doing. Then pulling said data from API and interacting with it. At least that's how the users that use the product I work on. Security, workflow, and cleanup are great examples.
- apples_oranges 1y agoI am involved in a project that has little documentation and many examples. It sucks. A good spec or manual is all you need. It's like googling "how to do XYZ with grep" instead of just typing "man grep" in the terminal.
- monegator 1y agoBullshit. Examples are the best excuse to not write documentation. I should be able to come up with an example by looking at the docs, not the other way around. I just LOVE IT when i read a device datasheet, perform the steps and things don't work. Then i have to download a couple of GB or so of framework and configurator to generate a project that shows me all the details they forgot to put in the datasheet: order of operations, missing requirements, all that stuff. Even better when the examples are not updated when the device / libraries / framework are updated
- NoSalt 1y agoIMHO, not just an "example", but a dead-simple example. Just show me the absolute bare minimum of what I need to do to get this working, and I can take it from there. It really doesn't help me when you build a book store from the ground up when I am only trying to learn a specific part.
- csours 1y agoThe "Real" documentation is the implementation. Prioritize making the source code available and understandable. Examples are very nice. One way to create examples is with test cases. Test cases can also be packaged with source code!
- 1718627440 1y agoThe user model an API exposes and the internal model to implement this can be very different. It's like trying to conclude from the transformation a clockwork does, what it's purpose is (keeping track of time passing). The user model never needs to occur explicitly in the code.
- intrasight 1y agoDocumentation is often wrong, incomplete, poorly written. If you only have N hours to work on "documentation", I say spend it on examples. Also AI can probably turn a quality example into a doc whereas it can't turn a doc into a quality example. Another thing to contemplate. I stand here as a 75 kilo entity - an example. I am, IHMO, a good example. The documentation on this example is so far many millions of page long, is very incomplete, certainly wrong, and could not be used to create said example.
- parpfish 1y agofor years, i've been secretly wishing that doctests would take off because it seems to really solve two problems at once: - it puts a simple usage example into the documentation - you get an easy-to-write, quick-to-run little assertion test that ensures basic functionality is saved
- tliltocatl 1y agoNo. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too much unsaid assumptions about the order of methods application.
- TZubiri 1y agoWhy not both? That way you can use the docs if you are learning the language AND if you already know the language but are looking for deep details.
- constant_flux 1y agoI agree. I don't understand some of the black and white thinking in the comments.
- tliltocatl 1y agoOf course both is best. But let's get real, once part one is there that's all you will get from the first-party. "Docs? Yes, here is our examples." Than for examples you can at least ask someone else if the lib is sufficiently popular. For the prose - gotta reverse-engineer it yourself.
- TZubiri 1y agoAs someone that reads official documentation instead of stackoverflow threads, I support this motion. There's a couple other maladies that make for unreadable docs. Another is documenting only the last layer added by the Open Source collaborator and not documenting anything below, for example if I'm making an HTTP client: http.get() makes an HTTP get request http.set_tcp_params(param=value) sets the TCP parameter param to value When you could do: http.get() makes an http get request, which should be a read only requaest, that doesn't affect state of the server. Parameters are typically passed in the URL with ?param=value¶m2=value2 syntax as defined in RFCxxx http.set_tcp_params() sets parameters of the tcp layer, as defined in RFCxxx, these can include most importantly the MTU which is the max packet size, which might be useful for fitting webpages... (<-- actually the reason the function was implemented at all, but then it was generalized just as an added bonus) One way to fail in this regard is to use one of those autodocs things, you just lost the battle.
- josefrichter 1y agoElixir world makes this easy: We advise developers to include examples in their documentation, often under their own ## Examples heading. To ensure examples do not get out of date, Elixir's test framework (ExUnit) provides a feature called doctests that allows developers to test the examples in their documentation. Doctests work by parsing out code samples starting with iex> from the documentation. You can read more about them at ExUnit.DocTest.
- bitwize 1y agoI'd say worked examples and comprehensive references are mutually reinforcing kinds of documentation, meaning you want both. I know I've gotten big mad at JavaScript library/framework documentation that had a few examples but when I actually wanted to learn the API in full, a reference was sorely missing. It was all cutesy "all you have to do is call wango.mumble() with your endpoints and pass the returned object into garthok.narfle() and it will autowire calls from the front end to back-end routes and you can use the time you saved to play with your doggo! :3" tutorial-y stuff. Good for standing up a simple app, but when I had to characterize the framework's behavior somehow I was staring at the source. PLEASE provide examples and PLEASE provide documentation of every API call's inputs, outputs, and effects.
- mlok 1y agoAlso : avoid using IT terms in examples (or "self-reference"), it can be confusing. In examples choose a very different field : animals, cars or anything, so that there is a very clear difference between language keywords (what needs to be learned) and the dummy data treated (what can be forgotten after reading). An example not to follow : https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots#using_the_element-details_custom_element_with_named_slots https://developer.mozilla.org/en-US/docs/Web/API/Web_compone... Here we are trying to explain templates and slots, with "slot" as an html attribute and the dummy data is... "slot". This kind of confusion is useless and makes it more difficult. Almost as if the goal was to be difficult.
- voidhorse 1y agoExamples are indeed crucial, but conceptual documentation and contract documentation that describes behaviors that cannot be formally made transparent in the language are equally important, and often missing too. In fact, I'd argue they are more important because an example can be easily misunderstood without this surrounding context.
- cultofmetatron 1y agoprobably one of the best uses of LLMs I've found in recent years. Needed to start integrating rabbitMQ into our application in order in integrate an external service. I had never worked with rabbitmq and while the docs for elixir's rabbitmq library were very good, it left me with a lot of open questions. I hopped on chatgpt and told it what my requirements were and it spat out with a boilerplate. for every scenario, I was able to have an example implementation generated. It still took an additional week of tweaking and changing things but This would have easily taken a month of exploratory programming pre chatgpt. Instead, we had a working proof of concept in a day and a half and had a final version deployed to prod in a month.
- rhodin 1y agoWhen I was working on Mathematica, a lot of effort was put in to making examples for each doc page. One example (that I didn't work on) picked at random: https://reference.wolfram.com/language/ref/RandomVariate.html https://reference.wolfram.com/language/ref/RandomVariate.htm...
- ChrisMarshallNY 1y agoThat's a big reason that I work hard on test harnesses[0]. [0] https://littlegreenviper.com/testing-harness-vs-unit/#sample https://littlegreenviper.com/testing-harness-vs-unit/#sample
- meander_water 1y agoI often need both. When I pull up a man page for a tool I haven't used before, I go to straight the bottom to look for an example that matches my use case. Once I have it, I lookup the the specific flags and what they do. Examples aren't meant to be exhaustive, but they certainly help onboard new people faster.
- Fire-Dragon-DoL 1y agoFor me examples are "shortcuts for the standard usecases". I use them do I don't have to understand the intricacies of the library. If I need more, i'll read the full doc. If I'm not in a standard usecase, I will read the full doc
- zzo38computer 1y agoIn my opinion, examples are very helpful, but are not the best documentation; real documentation is better. (It is good to have documentation with examples, and/or to have documentation and also separate examples. Having the source code of the program can also sometimes help with some things that the neither the documentation nor the examples makes clear.) I try to write good documentation for my programs, although it helps if other people (who do not already know the working of the program) will review it in order to suggest improvements.
- chopin 1y agoI regularly need reference docs in hour 2 of trying something new as the examples don't cover my use case.
- bb112 1y ago[dead]
- tomashm 1y agotldr; 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/ 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.