Simon Willison’s Weblog

30 items tagged “documentation”

2021

Making world-class docs takes effort (via) Curl maintainer Daniel Stenberg writes about his principles for good documentation. I agree with all of these: he emphasizes keeping docs in the repo, avoiding the temptation to exclusively generate them from code, featuring examples and ensuring every API you provide has documentation. Daniel describes an approach similar to the documentation unit tests I’ve been using for my own projects: he has scripts which scan the curl documentation to ensure not only that everything is documented but that each documentation area contains the same sections in the same order. # 6th September 2021, 6:58 pm

The Diátaxis documentation framework. Daniele Procida’s model of four types of technical documentation—tutorials, how-to guides, technical reference and explanation—now has a name: Diátaxis. # 21st August 2021, 10:59 pm

Datasette on Codespaces, sqlite-utils API reference documentation and other weeknotes

This week I broke my streak of not sending out the Datasette newsletter, figured out how to use Sphinx for Python class documentation, worked out how to run Datasette on GitHub Codespaces, implemented Datasette column metadata and got tantalizingly close to a solution for an elusive Datasette feature.

[... 2163 words]

Adding Sphinx autodoc to a project, and configuring Read The Docs to build it. My TIL notes from figuring out how to use sphinx-autodoc for the sqlite-utils reference documentation today. # 11th August 2021, 1:21 am

sqlite-utils API reference (via) I released sqlite-utils 3.15.1 today with just one change, but it’s a big one: I’ve added docstrings and type annotations to nearly every method in the library, and I’ve started using sphinx-autodoc to generate an API reference page in the documentation directly from those docstrings. I’ve deliberately avoided building this kind of documentation in the past because I so often see projects where the class reference is the ONLY documentation, which I find makes it really hard to figure out how to actually use it. sqlite-utils already has extensive narrative prose documentation so in this case I think it’s a useful enhancement—especially since the docstrings and type hints can help improve the usability of the library in IDEs and Jupyter notebooks. # 11th August 2021, 1:03 am

2020

Design Docs at Google. Useful description of the format used for software design docs at Google—informal documents of between 3 and 20 pages that outline the proposed design of a new project, discuss trade-offs that were considered and solicit feedback before the code starts to be written. # 7th August 2020, 4:31 pm

The unofficial Google Cloud Run FAQ. This is really useful: a no-fluff, content rich explanation of Google Cloud Run hosted as a GitHub repo that actively accepts pull requests from the community. It’s maintained by Ahmet Alp Balkan, a Cloud Run engineer who states “Googlers: If you find this repo useful, you should recognize the work internally, as I actively fight for alternative forms of content like this”. One of the hardest parts of working with AWS and GCP is digging through the marketing materials to figure out what the product actually does, so the more alternative forms of documentation like this the better. # 22nd July 2020, 5:20 pm

How to find what you want in the Django documentation (via) Useful guide by Matthew Segal to navigating the Django documentation, and tips for reading documentation in general. The Django docs have a great reputation so it’s easy to forget how intimidating they can be for newcomers: Matthew emphasizes that docs are rarely meant to be read in full: the trick is learning how to quickly search them for the things you need to understand right now. # 3rd July 2020, 3:04 pm

2019

Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances—so software usually needs them all.

Daniele Procida # 3rd August 2019, 8:29 am

2018

The subset of reStructuredText worth committing to memory

reStructuredText is the standard for documentation in the Python world.

[... 1183 words]

Honeycomb changelog (via) Too few hosted services have detailed user-facing changelogs. This one from Honeycomb (a metrics, tracing and observavility platform) is a particularly great example. I especially like the use of animated screenshots, something I’ve been evangelizing pretty heavily recently for internal communication at work. # 25th August 2018, 3:12 am

Documentation unit tests

Keeping documentation synchronized with an evolving codebase is difficult. Without extreme discipline, it’s easy for documentation to get out-of-date as new features are added.

[... 1518 words]

SpatiaLite — Datasette documentation. Datasette’s documentation now includes extensive coverage of the SpatiaLite extension for SQLite: how to install it, how to import latitude/longitude points, shapefiles and GeoJSON data into SpatiaLite tables, and how to run SQL queries against it that take advantage of spatial indexes. I’m learning SpatiaLite at the moment and filling out the documentation with each new trick I learn as I go—as Mark Pilgrim once taught me, the best way to learn a new technology is to write about it. # 30th May 2018, 4:34 am

2017

TLDR pages. This is an absurdly good idea: a community maintained set of alternative man pages for common commands with a focus on usage examples, plus a “tldr netstat” command to see them. The man pages themselves are maintained on GitHub. # 24th November 2017, 5:38 am

gitchangelog. Handy Python utility that can generate a reStructured Text changelog from your git commit log. I used this to help get the Datasette release notes started. # 16th November 2017, 4:52 pm

Datasette 0.12. I just released v0.12 of Datasette. The most exciting new feature is the ability to display a UI for editing named parameters—so you can construct an arbitrarily complex SQL query, include some named parameters and then link directly to it in Datasette to provide a simple interface for changing those parameters. An example involving Australian dogs is included in the release notes. # 16th November 2017, 3:55 pm

Doc of docs

Here’s a low-tech, high-impact trick I recently learned at work that’s amazingly useful: create a doc-of-docs.

[... 215 words]

2009

Writing good documentation (part 1). Jacob explains some of the philosophy behind Django’s documentation. Topical guides are particularly interesting—many projects skip them (leaving books to fill the gap) but they fill an essential gap between tutorials and low-level reference documentation. # 11th November 2009, 7:13 am

FireScope. Neat little Firefox / Firebug extension which adds a “Reference” tab showing documentation for the selected element from the comprehensive SitePoint Reference site. # 5th February 2009, 10:51 pm

2008

Django documentation (for 1.0). The documentation refactor is in: the docs for the upcoming 1.0 release have been tidied up, rearranged and ported to a new documentation system based on Sphinx (the Python documentation toolkit, NOT the full-text search engine). The URL has also changed to docs.djangoproject.com. # 24th August 2008, 10:49 am

GeoDjango Documentation. Merged to Django trunk a few hours ago. The tutorial isn’t there yet, but the rest of the docs are worth exploring. # 5th August 2008, 11:06 pm

Google Doctype. So now we know what Mark Pilgrim’s been doing at Google... heading up a project to create an encyclopaedia of web development. The JavaScript UI for browsing it is a bit weird (though you do at least get real pages if you disable JavaScript in your browser). # 14th May 2008, 8:30 pm

CSS Compatibility and Internet Explorer (via) Official Microsoft guide to which CSS properties are supported by which versions of IE. This is the kind of documentation browser vendors should be providing as a matter of course. # 2nd April 2008, 8:05 pm

Python-by-example. “This guide aims to show examples of use of all Python Library Reference functions, methods and classes”, thus addressing my number one complaint about Python’s standard library documentation. # 2nd April 2008, 3:42 pm

2007

Safari CSS Reference. Official documentation covering the CSS properties supported by Safari, including the -webkit proprietary extensions. # 22nd November 2007, 11:51 pm

Thoughts on (and pics of) the original Macintosh User Manual. “[I] was struck by how it had to explain a total paradigm shift in interacting with computers”. # 30th August 2007, 5:32 am

The Python docs have been redesigned for 2.6. They’re beautiful. The docs for a module are on a single page now (rather than splitting over multiple pages), they’ve added unobtrusive permalinks to individual sections and the whole thing is built on ReST rather than LaTeX. # 18th August 2007, 12:39 pm

Django-fr. Community site for French language Django developers. They’ve already made a promising start on translating the documentation. # 21st June 2007, 10:50 am

start.gotapi.com. Lightning fast lookups of API documentation; includes Python docs, YUI, HTML, CSS and lots more. # 5th June 2007, 6:05 pm

2005

The Dojo Manual (via) Dojo finally gets some really good extensive documentation. # 24th December 2005, 6:21 pm