Ask HN: What's the best SDK documentation you’ve ever read? 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! |
Ask HN: What's the best SDK documentation you’ve ever read? 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! |
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.
I think this is particularly a problem with Java docs because Java IDEs auto-insert useless documentation and people think "oh great it's documented".
M-: (info “(elisp)”) RET- 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.
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.
You can immediately tell the really good technical documentation written in that old school pattern by its usefulness when you don't know anything about the code being documented. Because the good technical editors bring to the table a discipline and enforcement of a judicious eye for perspective, constantly, maddeningly, repeatedly, asking ELI5 until the words coalesce into something I can appreciate as a newbie to its tech stack.
If you want to see the documentation rot really set into the commercial industry (the situation is better in the bigger open source projects), look for documentation between versions. A common commercial software dodge now is the documentation site has a way to switch between versions of the same topic, and the budget for technical writers being non-existent, someone makes the decision to "helpfully suggest" there isn't an "exact match" for the same topic in the other selected version, and would the user like to change to the homepage of the selected version?
Product owners have forgotten that well-edited and written documentation integrated into the support and development lifecycle is an enormously powerful vendor lock-in.
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.
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.
Why? They are comprehensive, detailed, consistent, systematically presented, clearly explained and professionally written. Microsoft documentation has sadly gone steeply downhill since.
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:
It's been this way for decades and the presentstion has remained largely consistent the whole time.
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. You frequently run into placeholder entries and some of the key Spring packages and classes lack sufficient overview javadoc. Spring's indifference to javadoc is deeply stupid. I can think of several cases where Spring users have written suboptimal programs where they fail to utilize the platform properly, and I'm certain this happens in-part because Spring's javadoc fails to guide them.
One case I ran into in the last little while is a system that implements a configuration file template system; Spring properties substituted into templates used to generate multiple complex (not 'context') configuration files. Unless you read the walls of Spring website documentation you won't know that Spring already provides exactly that capability and so the coders involved wrote their own half-baked one.
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:
Rust docs are decent too but not quite as good as Qt.
Lots of good docs have you visually doing the setup/work, then you realise you can download/see a bunch of code for all the actions you did (e.g. everything UI doable is programmable and the tools taught you all the concepts), it minimises the actual programming, it is really hard/time consuming to mentaly translate API docs to code.
I always appreciated Maven documentation too. Always verbose and you'll find more than enough information rather than none.
It's basically the only one I can think of in recent memory that basically spells out everything you need to know in the documentation.
Then with the advent of .Net (or, at least, around that time, say 2000+) things just ballooned and suddenly the MSDN became super difficult to navigate, almost overnight. Even today, there's a lot (a lot) there but it's nowhere near as useful as is used to be. The MSDN habit of providing a TOC to the left of any given article seems like it /should/ be useful, but instead it's been beaten to death. There must be a better way to navigate their documentation than that.
Also, surprisingly often links to other documentation are broken - that's not new, it's always been the case iirc, but it's much more prevalent these days.
And, some of their stuff has a lot of documentation, but it's just difficult to follow. I swear they're paying technical writers by the number of sections they can chop a give subject into. I was looking into Azure/Business Central documentation a while back and didn't find anything useful even though there's a ton of information there. I had ~10-15 tabs open all roughly referencing different pieces of what I thought I needed. Eventually, I stumbled across a dev blog, not MS, describing almost exactly what I needed, along with some crucial details that I never saw in Microsoft's documentation.