Example of Best Practice documentation for SDWWG

gistfile1.md

Better Living Through Documentation

http://datamade.us/blog/better-living-through-documentation/

A thorough list of recommendations on how to write developer-friendly documentation (and best practices). Contains many useful tips e.g. "don't put important content directly before or after a code snippet", "avoid the word 'just'" and "make sure code examples are okay to copy/paste".

OpenLayers 3 examples

http://openlayers.org/en/v3.8.2/examples/cluster.html

Executes the "easy copy/paste of code" mantra extremely well. Code is copied to clipboard or JSFiddle with a single click. The latter is extremely useful for doing quick, one-off experiments.

The Federal Election Commission API

https://api.open.fec.gov/developers

Crème de la crème of API documentation. Contains executable code, response examples, foldable code blocks, concise and to the pont text, enthusiastic calls for participation, etc.

mapschool

http://mapschool.io/

mapschool explains geo in an extremely basic, and therefore accessible, way. This is the level of complexity/simplicity that the Best Practice docs should strive for to achieve adoption by non-geo developers.

civic hacking and digital government initiatives

http://www.codeforamerica.org/ https://www.whitehouse.gov/digital/united-states-digital-service https://18f.gsa.gov/ https://gds.blog.gov.uk/

Are all great examples of large (non-commercial) organizations that engage with developers by building great tools and writing superb documentation, but also by opening their process to external contributions (see e.g. this and this) and being positively outspoken about it.

Noteworthy examples of documentation are U.S. Digital Service Playbook by USDS and U.S. Federal Web Design Standards by 18F. Both are open to contributions through GitHub.