I 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.
Examples are the best documentation
81–90 of 179 posts
Re: Examples are the best documentation
#82The 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/
This 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.
Re: Examples are the best documentation
#83Earlier quoted context omitted.
> £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.
I 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
> I don't use $ in programming except for string interpolation
... but the entire point of the "$JOB" etc. slang is that it's a string interpolation...
Re: Examples are the best documentation
#84Earlier quoted context omitted.
I 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
Oh no my PHPness is showing! Also, many, many countries use $, like Canada.
If 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)
Re: Examples are the best documentation
#85Bullshit.
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
Re: Examples are the best documentation
#86Please 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 t…
Documentation 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.
Re: Examples are the best documentation
#87Please 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…
I 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.
Re: Examples are the best documentation
#88Earlier quoted context omitted.
> £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.
I 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
Every time I use $word in a comment is to be reminiscent of POSIX-style string interpolation for some word. The vast majority of cases where I've seen it are such, only if "word" is numeric do I expect $ is used as a currency symbol.
Re: Examples are the best documentation
#89Earlier quoted context omitted.
I 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
> I don't use $ in programming except for string interpolation ... but the entire point of the "$JOB" etc. slang is that it's a string interpolation...
Not how I use it, string interpolation would be $"{job}"
Re: Examples are the best documentation
#90Please 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…
Personally - what you're asking for is type definitions.
And it's a blurry line, since type definitions are a good form of documentation. It's just that type-system tooling has mostly replaced the need to go read through the docs for that. I expect to get it easily and obviously in whatever editor or IDE I've configured.
I think the prevalence of example based documentation is because of this trend - don't waste time manually writing the same thing type tooling is going to give your users anyway.
When I hit docs - I'm much less interested in the specific arguments, and I'm very interested in "Capabilities": Problems this tool can solve.
Examples are a great showcase for that. Especially if I have a specific problem in mind and I just want to know if a "tool" can solve that problem, and how to use it to do so.
---
If I have a type system: I want examples first.
If I don't have a type system: 1) I'm not happy. 2) I want examples first, followed by the detailed arguments/return/data structure docs you're referring to.