Library Writing Realizations

• rasterio

  6 2,138 8.6 Python

  Rasterio reads and writes geospatial raster datasets

  

> X. People will not read the docs.

> Docs are almost useless. Nobody reads them.

> They'll read a one page quick start, and then they want to just start digging in writing code.

> Keep the intros very minimal and very focused on getting things working.

I, for one, read the docs. May fortune smile on those who put effort into https://rasterio.readthedocs.io/

They are terse, but enough breadcrumbs to fumble my way to a working input for gdal_proximity.py

Possibly I'm not a representative sample, but one of my mantras at the office is "If you ain't doc'in', you ain't rockin'."

(Though we are only doing ransom note wiki pages, not library documentation.)

If the package doesn't have shiny Sphynx docs, at least afford us a few cryptic utterances in the source code.

• yesql

  4 1,444 0.0 Clojure

  A Clojure library for using SQL.

> People will not read the docs.

Reminds me of a pull request I made a while ago

https://github.com/krisajenkins/yesql/pull/151/files

The first piece of code on the readme is "not the solution" (lol), and everybody I knew who was trying to use that library was copy-pasting that specific piece of code from the readme.

• WorkOS

  workos.com sponsored

  The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.

  

Suggest a related project