DEV Community

Ben Halpern
Ben Halpern

Posted on

What are some examples of great documentation?

I'd love to see some projects that do documentation very well for inspiration!

Top comments (40)

Collapse
 
ianhopkinson_ profile image
Ian

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/

Collapse
 
danieljsummers profile image
Daniel J. Summers

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.

Collapse
 
mubashariqbal profile image
Mubashar Iqbal

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

Collapse
 
hawarioware profile image
Wajdi Al-Hawari

Came here to post about Stripe. Totally agree. +1

Collapse
 
ky1e_s profile image
Kyle Stephens

Came here to post Stripe. .

Very accessible, clear, concise and with strong examples in many languages.

stripe.com/docs/api

Collapse
 
elijahschow profile image
Elijah Schow • Edited

Positive Examples:

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

Edit: Bootstrap v4's documentation fixes most of the problems in v3's.

Collapse
 
jesseditson profile image
Jesse Ditson

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.

Collapse
 
hcrudolph profile image
Hans Christian Rudolph • Edited

Django's docs are great to work with, concise and available in many different languages.

Collapse
 
duffn profile image
Nicholas Duffy

Django's docs are the absolute best.

Collapse
 
sbouaked profile image
Samir Bouaked

Always been a big fan of the Algolia documentation : algolia.com/doc/

Collapse
 
zachberger profile image
Zach Berger • Edited

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.

Collapse
 
meangrape profile image
Jay.

OpenBSD man pages. PostgreSQL documentation. Illumos source code.

Collapse
 
galvao profile image
Er GalvΓ£o Abbott

+1 for PostgreSQL docs.

Collapse
 
berkus profile image
Berkus Decker

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.

Collapse
 
asturur profile image
Andrea Bogazzi

i wish i could filter them from my google searches. and do not forget the terrible automatic translations

Collapse
 
kroegr profile image
Andree KrΓΆger • Edited

I will give only positive examples:
Material Design
Google Guice
Mockito

Collapse
 
thetrentharvey profile image
Trent Harvey

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.

Collapse
 
nick profile image
Nick Rameau

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 :)

Collapse
 
pavonz profile image
Andrea Pavoni

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

Collapse
 
asturur profile image
Andrea Bogazzi

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