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.
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
TIL this week
More recent articles
- Weeknotes: Embeddings, more embeddings and Datasette Cloud - 17th September 2023
- Build an image search engine with llm-clip, chat with models with llm chat - 12th September 2023
- LLM now provides tools for working with embeddings - 4th September 2023
- Datasette 1.0a4 and 1.0a5, plus weeknotes - 30th August 2023
- Making Large Language Models work for you - 27th August 2023
- Datasette Cloud, Datasette 1.0a3, llm-mlc and more - 16th August 2023
- How I make annotated presentations - 6th August 2023
- Weeknotes: Plugins for LLM, sqlite-utils and Datasette - 5th August 2023
- Catching up on the weird world of LLMs - 3rd August 2023
- Run Llama 2 on your own Mac using LLM and Homebrew - 1st August 2023