Maybe not quite on topic but I think the Physically Based Rendering book which combined code and documentation in the literate programming style is excellent: pbrt.org/
Mozilla Developer Network (MDN) has helped me immensely; they document JavaScript (in particular) at a level where it's a good reference. It's complete, yet it doesn't assume an overly high level of knowledge.
Google something + "Digital Ocean". e.g. "Deploy NodeJS DigitalOcean". You'll probably get a pretty good guide.
Negative Examples:
MongoDB - ...where do I even start? Literally. Where?
Mongoose - they eventually make sense, but only once you're already are familiar with how mongoose works...
Bootstrap v3 - This is contentious, but even after years of using Bootstrap, I always have difficulty finding stuff in the docs. I can never remember what's in the "CSS" vs "Components" vs "JavaScript" tabs and the navigation sidebar is painful to use
I love building things, mostly with code.
Currently: Software Engineering Architect at Quip (Salesforce). Previously Attic Labs and a bunch of startups.
I'd second stripe in that their docs pretty pleasurable to look at, although I would say they can be a bit lacking when it comes to documenting references (lots of "see account update docs for full object", which at times isn't totally accurate).
Golang probably has the best documentation I've ever seen - it's not much to look at, but you can go from never writing a line of go to understanding it at a pretty deep level without ever leaving the site. There are both interactive docs and a a book on best practices directly on the site.
I was recently really impressed by the AirTable API docs, which take stripe's "docs on the left, code on the right" paradigm to a new level by contextualizing the docs to an existing project (step one is to select your project, step two is browse the docs with all your table names and stuff filled in). As such, "writing" code that interfaces with the API is primarily copy pasta, which is pretty productive. Not sure if it would scale to a more abstract API but this approach is fantastic for tables.
Information security expert specializing in network and infrastructure security. Also equipped with a strong affinity for programming languages and their underlying concepts.
I'm a big fan of Parse's documentation. There is a good balance between narrative and working code examples. Additionally, the navigation is superb; you are never more than two clicks from any other section of the documentation for the entire platform.
Negative examples: MSDN (with the "DWORD dwFlags -- a dword containing flags" style of descriptions) and Boost - where each library has it's own unique style of documentation and usually lacks badly on EXPLAINING the usage of the library in the right way.
Apple has done an amazing job at thorough documentation of their iOS platform and all the related libraries and concepts. I easily rank them and PHP's official documentation as some of the best examples of how to document a platform/system.
Well, it's cool that people are sharing popular documentations. It's mostly a result of a lot of contributions from a lot of people or a dedicated team.
What about documentations of a small team about a small to medium sized project? Nobody? I gotta say I'm disappointed.
Well, I'm shamelessly going to share one of mines because I believe you don't come up with documentations almost as perfect as the ones shared here, you build upon them.
My project documentations are definitely not the best out here, we already have enough great recommendations here to satisfy this post so I thought it would be okay to be different at this point.
I believe you have to start somewhere and I recommend, for a small to medium project, to take example of the documentation of my project called Libft as an example:
I'm a dev with a strong *NIX sysadmin background. I've been programming for 20+ years, started with IRC scripts, C, Python, PHP, Ruby/Rails, Node/JS, Go and Elxir. Full time on Ruby,Elixir and Rust.
Maybe the best examples I've seen are Go and Elixir.
In Elixir, you cam write the main documentation for a module, for each public function and... write examples that can be run as real tests! They are, indeed, called "doctest" elixir-lang.org/getting-started/mi...
Golang has an excellent documentation system: it lets you edit/run the code in examples.
I've mentioned documentation systems rather than specific projects docs. Well, sometimes is the doc system that incentivizes writing docs. That's why Elixir, Golang and many other technologies usually have good documentation.
I raise the Twitch.tv API. Been working on a project with using a Google API and the Twitch API. They are polar opposites. Twitch's API is clear, concise, and a pleasure to work with. Implementing Twitch features doesn't take a lot of time. It truly feels like intelligent developers made it.
Saying that Google's Calendar API is stressful, confusing, and messy is a serious understatement. It's a mountainous trash fire, right next to a fire engine manned by human-sized rainbow shrimp spraying gasoline onto the flames. At least, that's what it feels like.
Also, the MDN is my first stop for anything JavaScript, HTML, or CSS related.
No BS. Code examples right there next to the content, without breaking the flow of the page. Live inline examples, again with the relevant code presented. I was definitely impressed the first time I arrived.
Also, I would love to see more documentation using Klipse or similar, so you can tweak and play around with the examples within the documentation pages themselves.
Bootstrap v3: You can't navigate between pages without scrolling all the way back up, elements are spread randomly between CSS and Conponents. A long and useless icon reference takes all the space at the very beginning of the Components page.
PHP: there's no per-version docs, you have to solve a logic puzzle spread between multiple aside boxes to know what you can do with a function on a given PHP version. Navigation is aweful.
Doctrine: everything is there, but it's impossible to find without a trip through Google. For a long time the API reference wasn't reachable from the documentation pages.
Terrific JS: everything is spread randomly: when you need to know how to do something, you cannot find it because it's not in its logical place. If you don't know something is possible, you will never find out. The only ways to use these docs are a) to read them all in sequence, in one sitting, and learn everything by heart'or b) to read everything every time you need to look up something.
Have had many hats on in my life: Developer, Team Lead, Scrum Master, Architect and Product Owner. Now back to developer \o/ Interested in product discovery, quality assurance and language design.
Programming 35+ years, including 25+ years of web app development for document management. Recent work with web components and Lit, as well as Java apps.
I love to code, and i love javascript. It's not the perfect language but it gets things done. I also love bringing UI designs to life with subtle and intuitive animations.
Rust documentation -- doc.rust-lang.org and docs.rs -- both as a resource and a tool. All documentation examples are compiled and run as tests to make sure they can't go out of date!
Maybe not quite on topic but I think the Physically Based Rendering book which combined code and documentation in the literate programming style is excellent:
pbrt.org/
Mozilla Developer Network (MDN) has helped me immensely; they document JavaScript (in particular) at a level where it's a good reference. It's complete, yet it doesn't assume an overly high level of knowledge.
Always been a big fan of the Stripe Docs:
stripe.com/docs
Also the Laravel docs are pretty awesome, the search is really good too:
laravel.com/docs
Came here to post about Stripe. Totally agree. +1
Came here to post Stripe. .
Very accessible, clear, concise and with strong examples in many languages.
stripe.com/docs/api
Positive Examples:
Negative Examples:
Edit: Bootstrap v4's documentation fixes most of the problems in v3's.
I'd second stripe in that their docs pretty pleasurable to look at, although I would say they can be a bit lacking when it comes to documenting references (lots of "see account update docs for full object", which at times isn't totally accurate).
Golang probably has the best documentation I've ever seen - it's not much to look at, but you can go from never writing a line of go to understanding it at a pretty deep level without ever leaving the site. There are both interactive docs and a a book on best practices directly on the site.
I was recently really impressed by the AirTable API docs, which take stripe's "docs on the left, code on the right" paradigm to a new level by contextualizing the docs to an existing project (step one is to select your project, step two is browse the docs with all your table names and stuff filled in). As such, "writing" code that interfaces with the API is primarily copy pasta, which is pretty productive. Not sure if it would scale to a more abstract API but this approach is fantastic for tables.
Django's docs are great to work with, concise and available in many different languages.
Django's docs are the absolute best.
Always been a big fan of the Algolia documentation : algolia.com/doc/
I'm a big fan of Parse's documentation. There is a good balance between narrative and working code examples. Additionally, the navigation is superb; you are never more than two clicks from any other section of the documentation for the entire platform.
OpenBSD man pages. PostgreSQL documentation. Illumos source code.
+1 for PostgreSQL docs.
So many comments and nobody mentioned Qt?
Qt docs are rather detailed and very helpful.
Negative examples: MSDN (with the "DWORD dwFlags -- a dword containing flags" style of descriptions) and Boost - where each library has it's own unique style of documentation and usually lacks badly on EXPLAINING the usage of the library in the right way.
i wish i could filter them from my google searches. and do not forget the terrible automatic translations
I will give only positive examples:
Material Design
Google Guice
Mockito
Apple has done an amazing job at thorough documentation of their iOS platform and all the related libraries and concepts. I easily rank them and PHP's official documentation as some of the best examples of how to document a platform/system.
Well, it's cool that people are sharing popular documentations. It's mostly a result of a lot of contributions from a lot of people or a dedicated team.
What about documentations of a small team about a small to medium sized project? Nobody? I gotta say I'm disappointed.
Well, I'm shamelessly going to share one of mines because I believe you don't come up with documentations almost as perfect as the ones shared here, you build upon them.
My project documentations are definitely not the best out here, we already have enough great recommendations here to satisfy this post so I thought it would be okay to be different at this point.
I believe you have to start somewhere and I recommend, for a small to medium project, to take example of the documentation of my project called Libft as an example:
github.com/r4meau/libft
It's hosted on Github as README file and extended in a Wiki. I'm open to any critic :)
Maybe the best examples I've seen are Go and Elixir.
In Elixir, you cam write the main documentation for a module, for each public function and... write examples that can be run as real tests! They are, indeed, called "doctest" elixir-lang.org/getting-started/mi...
Golang has an excellent documentation system: it lets you edit/run the code in examples.
I've mentioned documentation systems rather than specific projects docs. Well, sometimes is the doc system that incentivizes writing docs. That's why Elixir, Golang and many other technologies usually have good documentation.
My 2cents
I' m mantainer of a small project ( small like one ) and i find super hard keeping documentation ok. Infact i m not managing at all.
I m trying to document it at best, but is not easy, dedicating time is not enough, you have also to know how to write nice docs and introductions.
the projects is fabricjs.com
I raise the Twitch.tv API. Been working on a project with using a Google API and the Twitch API. They are polar opposites. Twitch's API is clear, concise, and a pleasure to work with. Implementing Twitch features doesn't take a lot of time. It truly feels like intelligent developers made it.
Saying that Google's Calendar API is stressful, confusing, and messy is a serious understatement. It's a mountainous trash fire, right next to a fire engine manned by human-sized rainbow shrimp spraying gasoline onto the flames. At least, that's what it feels like.
Also, the MDN is my first stop for anything JavaScript, HTML, or CSS related.
React Router Docs
No BS. Code examples right there next to the content, without breaking the flow of the page. Live inline examples, again with the relevant code presented. I was definitely impressed the first time I arrived.
I am - not without some bias, I suppose - a huge fan of PHP's Documentation. It has all the good points:
And it's even downloadable in HTML and CHM formats. Honestly, I don't know what else you could ask for in language docs.
I am really impressed with re-frame and KafkaStreams
Also, I would love to see more documentation using Klipse or similar, so you can tweak and play around with the examples within the documentation pages themselves.
Oracle: docs.oracle.com/database/122/nav/p...
A huge range, available online or as PDF, Mobi or ePub downloads, with a range of detail (Concept / Guide / Reference), consistently formatted.
The SQL Reference for 12.2 is over 2,000 pages.
With Oracle, it's pretty rare that you can't legitimately tell someone to go RTFM.
Not an example for a good codebase but given most people who read this work on their own doc pages:
The #1 rule for documentation is that it has to be autogenerated and/or automatically tested.
As soon as it has to be manually updated and/or it's external from your codebase people won't do it.
Eg. your api docs should be generated with your automatic tests. At @producthunt we use eg github.com/zipmark/rspec_api_docum... for this.
Negative examples:
Bootstrap v3: You can't navigate between pages without scrolling all the way back up, elements are spread randomly between CSS and Conponents. A long and useless icon reference takes all the space at the very beginning of the Components page.
PHP: there's no per-version docs, you have to solve a logic puzzle spread between multiple aside boxes to know what you can do with a function on a given PHP version. Navigation is aweful.
Doctrine: everything is there, but it's impossible to find without a trip through Google. For a long time the API reference wasn't reachable from the documentation pages.
Terrific JS: everything is spread randomly: when you need to know how to do something, you cannot find it because it's not in its logical place. If you don't know something is possible, you will never find out. The only ways to use these docs are a) to read them all in sequence, in one sitting, and learn everything by heart'or b) to read everything every time you need to look up something.
At least from what I know from 5 or so years ago, Qt's documentation is one of the best I've worked with so far: doc.qt.io/qt-5/reference-overview....
I like boto3: boto3.readthedocs.io/en/latest/ind...
The new release of akka docs
The JDK's JavaDocs. I wish JavaScript libraries were so consistently formatted.
+1 for the VueJS guide
docs.djangoproject.com/en/1.11/ is the most complete documentation i've seen.
Rust documentation -- doc.rust-lang.org and docs.rs -- both as a resource and a tool. All documentation examples are compiled and run as tests to make sure they can't go out of date!
Laravel docs: laravel.com/docs/5.5/
Mojolicious
Redis: The example blocks are actually a console where you can play with the sample commands, modify them and type new ones.
Particle.io
I like Microsoft's technical documentation that's hosted on GitHub (e.g. the Azure documentation).