loading...

Favorite Examples of Clear, Understandable Documentation?

rachel_cheuk profile image Rachel ・1 min read

What guidance exists for writing technical documentation?

What are some of your favorite examples for easy to understand documentation when tackling a new framework, language, or library?

Discussion

markdown guide
 

Hi Rachel!

I compiled a list of technical writing resources; you'll find books, courses, and links to documentation style guides from GitLab, DigitalOcean, Google, and Microsoft. Hope this helps!

 

Dope! Thanks for upping that to GH! πŸ’―β€βœŒ

 
 

I really like the documentation of the Python library scikit-learn. It’s structure provides an accessible section for newcomers with introductions, tutorials ad examples. But also the class-by-class documentation contains lots of details, usefull cross references, etc.

 

Check out Laravel and Vue docs :)

 

Laravel design is always of such a good taste.

 

I've been working on rewriting the Redux core docs, and collected some notes and resource links on good docs writing practices.

I particularly liked the article What Nobody Tells You About Documentation.

On that note, I just published a brand new "Redux Essentials" tutorial that was written using the lessons I'd learned from those resources.

 
 

Spring Boot and Spring Framework documentation sites are terse, easy to read, as detailed as they can be and well styled. All the corpus says "professionally organized" and "well-thought". That's not easy, given all the functionality that both products cover.

 

The best documentation that I've seen is the DigitalOcean API documentation.

For a small opensource project I believe that Laravel Voyager has some great docs as well.

 

The tidyverse documentation is phenomenal.

In R we have a few conventions for documentation, which includes both short form (per function) documentation, but also long form (vignettes). Because we also have R markdown these are both driven by the language itself.

In addition we also have packagedown, which turns docs into websites, though I'm sure this exists in python in a similar form as well.

 

I haven't read it in a long time (for reasons) but back in the early 2000s the PHP documentation was amazing.

Each function had a clear explanation with clear examples plus user contributions for edge cases.

I haven't found easier to understand documentation since.

 

Actually, if I can broaden the definition of documentation, Gatherer, the Magic: the Gathering card index, is pretty great.

 

I can tell you that whoever writes NordVPN's copy for their release/patch notes deserves a raise:

nordvpn.com/blog/nordvpn-windows-r...

IMO, a perfect blend of technical and plain talk.

+1 for the Vue specialization!

πŸ’―β€βœŒ