Weeknotes: Datasette Tutorials
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.
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
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