Simon Willison’s Weblog

Weeknotes: Datasette Tutorials

27th February 2022

I published two new tutorials for Datasette this week, both focused at end-users of the web application.

Exploring a database with Datasette shows how to use Datasette as an exploratory data analysis tool, using facets and filters to get a good feeling for a new database.

Learn SQL with Datasette introduces Datasette’s SQL query interface and uses it to teach basic SQL as well as a few more advanced tricks too.

Datasette already has a lot of documentation, but so far it’s all been written to serve people who are administering or customizing Datasette instances. The user interface itself has been mostly undocumented.

Daniele Procida’s Diátaxis documentation framework describes four categories of documentation: tutorials, how-to guides, technical reference and explanation. Datasette is heavy on the last two but light on the first.

These new tutorials are my initial attempt at redressing the balance. I adapted them from a workshop I presented on Friday at the FOIA Fest data journalism conference in (virtual) Chicago.

Writing documentation for end-users has been an interesting experience! I chose to lean heavily into screenshots, live examples and exercises. I’m eager for feedback from people to help me understand if what I’ve done is working, and I’m keen for suggestions on how to improve them and what to write next.

The example database I used for the tutorial is pretty fun: https://congress-legislators.datasettes.com—a database of USA senators, congresspeople, presidents and vice presidents built using CC0 data from the absolutely brilliant unitedstates/congress-legislators repository (which just accepted my first PR!)

This was my first attempt at writing end-user facing documentation for a personal project, and it turned out to have the same effect as writing developer documentation: the moment you try to describe how to use a feature the flaws in how that feature works from a usability perspective become strikingly evident!

I’m convinced that writing comprehensive documentation is a massively underrated technique for better software design.

Releases this week

• datasette-render-markdown: 2.1—(9 releases total)—2022-02-26
  Datasette plugin for rendering Markdown
• datasette-redirect-forbidden: 0.1—2022-02-23
  Redirect forbidden requests to a login page
• sqlite-diffable: 0.2.1—(3 releases total)—2022-02-21
  Tools for dumping/loading a SQLite database to diffable directory structure
• google-drive-to-sqlite: 0.4—(6 releases total)—2022-02-20
  Create a SQLite database containing metadata from Google Drive
• sqlite-utils: 3.24—(96 releases total)—2022-02-16
  Python CLI utility and library for manipulating SQLite databases

TIL this week

• Combining substr and instr to extract text
• Google OAuth for a CLI application
• Recursively fetching metadata for all files in a Google Drive folder
• Using curl to run GraphQL queries from the command line