31–40 of 51 posts
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.
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.
does this count? M-: (info “(elisp)”) RET
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.
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 d…
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.
I always appreciated Maven documentation too. Always verbose and you'll find more than enough information rather than none.
I know there are lot of hate for Java but I find Java Doc very complete and helpful.
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.
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.
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
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.
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.
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.