[HN Gopher] Whats the best SDK documentation you've ever read, a...
___________________________________________________________________
Whats the best SDK documentation you've ever read, and why?
Finding a good sdk is hard. Finding a well documented one is
harder. Would love to see what you consider as the golden standard
for documenting sdks!
Author : sethx
Score : 27 points
Date : 2022-09-10 20:27 UTC (2 hours ago)
| dmitrygr wrote:
| This one:
| https://stuff.mit.edu/afs/sipb/user/yonah/docs/Palm%20OS%20R...
| tangerine11 wrote:
| The maven documentation is worth mentioning here. It it's useful
| for my area of Android dev and has also made me laugh with it's
| bluntness.
| richardcrossley wrote:
| The Windows 3.1 SDK. I bought and read it at University, some
| decades ago, and I can still write simple C programs for Windows
| that compile under Windows 2000 and run under Windows 10.
| taeric wrote:
| The TeX-Book. Really fun read that presents the system with
| exercises that are approachable.
| zanethomas wrote:
| I think the documentation for Vue is pretty good.
| GnarfGnarf wrote:
| I find the Qt documentation to be excellent. If only Microsoft
| rose to the same level of helpfulness.
| danellis wrote:
| RISC OS Programmer's Reference Manual. It's very well laid out,
| clearly written and consistent. In fact, I even bought myself a
| copy all these years later to peruse for nostalgia.
| zetalyrae wrote:
| This will be an unusual answer: the Inform documentation. It is
| some of the best, most compelling technical prose I've ever read.
| The stability of it is very calming when everything else in
| programming is in a perpetual state of simultaneous development
| and deprecation.
|
| The two books are "Writing with Inform" and "The Inform Recipe
| Book":
|
| https://ganelson.github.io/inform-website/book/WI_1_1.html
|
| https://ganelson.github.io/inform-website/book/RB_1_1.html
|
| Inform is a weird beast: it is a domain-specific language for
| writing interactive fiction stories, with natural English
| language syntax. But underneath there's an object model and
| datatypes and you can use it as a general-purpose language:
| https://learnxinyminutes.com/docs/inform7/
|
| Additionally, there's "The Inform Designer's Manual", which is
| for an earlier version using a more standard programming language
| syntax:
|
| https://www.inform-fiction.org/manual/html/index.html
| jtreminio wrote:
| Use openapi and many of the documentation generators will create
| great reference pages.
| thenerdhead wrote:
| Stripe always stood out in terms of SDK documentation. Never had
| an issue from start to finish.
|
| I always appreciated Maven documentation too. Always verbose and
| you'll find more than enough information rather than none.
| donio wrote:
| Nobody would call it an "SDK" but I find the Emacs/Elisp
| documentation to be excellent both on the docstring level and the
| manuals. It has been refined over several decades, it is
| thorough, well written and very easy to use from the comfort of
| Emacs itself.
| aeturnum wrote:
| I'm extremely fond of the official Elixir documentation - it's
| easy to read, has a standard structure, and most importantly (to
| me) you can click the "code symbol" (</>) to go to the actual
| implementation of the function documented.
|
| https://hexdocs.pm/elixir/Enum.html#flat_map/2
| hprotagonist wrote:
| does this count? M-: (info "(elisp)") RET
| GeorgeTirebiter wrote:
| M-: (info "elisp") RET
| srik wrote:
| Tailwind. Since tailwind classes expand to css, they could've
| called it a day by just showing those expansions, but they went
| further and each class has it's own section and every variant
| comes with an explanation, often accompanied with illustrations
| even. Their designer roots show too, because the illustrations
| are tight. Honestly, one could potentially skip having to refer
| to css docs and make do with just tailwind's.
|
| https://tailwindcss.com/docs/installation
| jasone wrote:
| The FreeBSD manual pages. They are thorough, accurate, and well
| maintained. I still refer to them on occasion even though I've
| not actively developed on FreeBSD for the better part of a decade
| now.
| aljgz wrote:
| Strictly speaking, it's not an SDK, but postgresql's official
| documentation is the best I have seen. Very easy to find what
| you're looking for, very approachable for beginners, yet
| versatile for the one who needs to dig deeper.
| kaladin-jasnah wrote:
| GStreamer is incredibly well documented from when I tried it.
| ihaveajob wrote:
| Stripe's documentation was terrific when we were doing our
| initial integration. Clear descriptions, frequent use cases were
| described and indexed so they're easy to find, and the code
| samples (in 6-8 languages) are copy-paste ready using your own
| pre-populated credentials.
| highwind wrote:
| I know there are lot of hate for Java but I find Java Doc very
| complete and helpful.
| cosmotic wrote:
| Java docs are great because they document: * technical details
| and algorithms used * side effects * runtime and memory usage *
| inputs that result in undefined behavior * causes of exceptions
| * behavior when accessed concurrently * thoroughly hyperlinked
|
| It's been this way for decades and the presentstion has
| remained largely consistent the whole time.
| topspin wrote:
| Second this. The core SDK and many common libraries are very
| well served by javadoc. I believe this is a key aspect of the
| success of Java. Javadoc serves so well that it compels Java
| developers to use it; you can tell if you're dealing with
| 'good' work or not by the thoroughness of the javadoc work.
|
| Spring has often frustrated me in this regard. Spring's website
| is thorough and nearly everything you might need can be found
| there with enough wading, but Spring's javadoc is often
| lacking. This poses a problem, for instance, when dealing with
| different versions. Spring's indifference to javadoc is deeply
| stupid.
| bitwize wrote:
| The man pages to NetBSD. I don't think I've seen such
| comprehensive documentation in all my born days. Every command,
| API, data structure, and concept in the base system is thoroughly
| documented. I managed to write a toy device driver and
| incorporate it into the kernel, using nothing but the man pages.
| rtdgggvvgg wrote:
| Not related to sdk but i Remember the hlp of visual basic like
| One of the best docs ever edit: because of the code snippets
| redwoolf wrote:
| The Android SDK is well documented with examples throughout and
| hyperlinked to examples and posts which explain some content in
| greater depth.
| Aaargh20318 wrote:
| Did they improve it recently ? I haven't developed for Android
| in a while but it used to be terrible. Full of absolutely
| useless method descriptions.
|
| For example, I remember getting frustrated because of the docs
| for a setTextSize method, with the helpful description "sets
| the text size". Nice. Very helpful that it didn't mention what
| unit the parameter was, especially since (after
| experimentation) it turns out the unit is not the one you would
| expect for a font size.
|
| The API docs were full of that kind of 'documentation', setX:
| "Sets X".
|
| If you are writing documentation, please explain what method
| parameters and return values actually mean, what the units used
| are. Especially if uses a unit no one expects. For example:
| font sizes are usually specified in points, if you expect them
| to be specified in pixels you should absolutely mention that.
| drpixie wrote:
| Really? Most of it seems to be machine generated from the code
| definitions - very little explanation, very little usage info.
| I find it terrible.
| Max-q wrote:
| When I was 10, I got my first computer. A Commodore VIC 20. The
| book that came with the machine taught me programming. It was
| very well written and already at 11 I could program quite well. I
| wish we could take more inspiration from that period when writing
| modern documentation.
| stevenwoo wrote:
| Do you mean this one or some other one?
| https://archive.org/details/Personal_Computing_On_The_VIC-20...
| omnicognate wrote:
| I don't have a view on SDK documentation but the best API
| documentation I've read is the Win32 docs.
|
| Why? They are comprehensive, detailed, consistent, systematically
| presented, clearly explained and professionally written.
| Microsoft documentation has sadly gone steeply downhill since.
| stevenwoo wrote:
| What year? I can remember around 1998? having difficulty with
| the foreign language IME and having to delve through the disks
| we got from MSDN or something?(I forgot the name) from our
| annual subscription to figure out the details of using it and
| finding out it was only documented with examples in a prior
| year we did not have and having to dig up the example files
| someone helpfully archived on their non Microsoft website (it
| was scrubbed from the Microsoft website for some reason). Then
| I noticed some other poor developer have the exact same issue
| (so it wasn't just me!) on usenet so I just emailed the files
| to him.
| userbinator wrote:
| I still use Win32.hlp for most of my reference needs.
|
| _Microsoft documentation has sadly gone steeply downhill
| since._
|
| I heard they decided to get rid of most of their documentation
| writers, and instead rely on "the community" to do it for them.
| And this horrible migration to a new system, which was
| basically an act that only the team doing it seems to be proud
| of:
|
| https://news.ycombinator.com/item?id=11626886
| ChrisMarshallNY wrote:
| I suspect that the PHP documentation has been the most effective.
|
| I know everyone likes hating on PHP, but the docs actually work
| very well.
|
| Part of it is because the language is basically a big standard
| library of functions, and those are easy to document, but the
| integration of user comments into each page has also been
| extremely useful to me.
|
| Inside Macintosh (Apple's original system docs) was very good.
| Apple's documentation has steadily degraded, since. The
| documentation for SwiftUI is basically worthless.
| gregsadetsky wrote:
| Agreed! I remember going from mainly writing PHP to Python many
| years ago and being specifically irked at how Python's core
| docs, unlike PHP's, didn't "clearly" (in my view) list
| arguments and, importantly, examples.
|
| PHP's one-page-per-func just seemed like a better way of
| focussing on/laying out everything there was to know about one
| function. This page [0] looks like it hasn't changed much in
| the last 15 years and absolutely brings back memories.
|
| [0] https://www.php.net/manual/en/function.str-ends-with
| gsliepen wrote:
| For C and C++: cppreference.com. Why?
|
| - Very good overview pages.
|
| - Everything is cross-referenced.
|
| - Almost everything comes with an example of how to use it.
|
| - It's a wiki, so you can edit it yourself if you find anything
| lacking.
| kaba0 wrote:
| Maybe it's just me being stupid, but cppreference, while
| absolutely of great quality, some c++ pages can be as cryptic
| as it gets. I know, the language is very much not trivial due
| to all these features, but for example the page about the
| different kind of l/rvalues is very very complex.
| fsflyer wrote:
| The original Inside Macintosh: https://www.pagetable.com/?p=50
|
| and the Human Interface Guidelines:
| https://archive.org/details/applehumaninterf00appl
|
| Lots of overview material explaining how it all fits together, as
| it was a big change from the past.
___________________________________________________________________
(page generated 2022-09-10 23:00 UTC)